Benelog Tech Notes

Call by Value vs. Call by Reference

Sat, 3 Oct 2026 00:00:00 +0000

You often hear that "in Java method calls, primitive types are passed by call by value and objects are passed by call by reference." Java, however, has only call by value. When you pass an object to a method, the value that gets copied is simply a reference that points to the object. This article lays out the definitions of the two terms and compares how Java, Kotlin, JavaScript, C, C++, C#, Python, Go, Rust, and Ada pass arguments.

Call by Value and Call by Reference

Call by value initializes a separate variable, the parameter, with the value passed as the argument. The value is usually copied, though some languages such as Rust move ownership instead. Assigning a different value to the parameter inside the function does not affect the caller’s variable.

Call by reference passes the variable itself. The parameter becomes an alias of the caller’s variable, so assigning a new value to the parameter inside the function also changes the caller’s variable.

These definitions follow the standard treatment in programming language theory.

Section 1.6.6 of Compilers: Principles, Techniques, and Tools, 2nd edition, describes the two mechanisms as follows.

In call-by-value, the actual parameter is evaluated (if it is an expression) or copied (if it is a variable). The value is placed in the location belonging to the corresponding formal parameter of the called procedure. This method is used in C and Java, and is a common option in C++, as well as in most other languages. …

In call-by-reference, the address of the actual parameter is passed to the callee as the value of the corresponding formal parameter. Uses of the formal parameter in the code of the callee are implemented by following this pointer to the location indicated by the caller. Changes to the formal parameter thus appear as changes to the actual parameter.

— Alfred V. Aho, Monica S. Lam, Ravi Sethi, Jeffrey D. Ullman
Compilers: Principles, Techniques, and Tools, 2nd edition, Section 1.6.6

The "actual parameter" in the quote corresponds to what this article calls an argument, and the "formal parameter" corresponds to what this article calls a parameter. Together with its 1977 predecessor Principles of Compiler Design, this book has served as the standard textbook for university compiler courses. Its cover illustration earned it the nickname "the Dragon Book."

Figure 1. Cover of Compilers: Principles, Techniques, and Tools, 2nd edition (image source: Open Library)

Christopher Strachey explained the distinction in terms of L-values and R-values in Section 3.4.2 of Fundamental Concepts in Programming Languages, his 1967 lecture notes. He called passing the R-value of an expression to a parameter call by value, and passing its L-value call by reference.

When the function is used (or called or applied) we write f[ε] where ε can be an expression. If we are using a referentially transparent language all we require to know about the expression ε in order to evaluate f[ε] is its value. There are, however, two sorts of value, so we have to decide whether to supply the R-value or the L-value of ε to the function f. Either is possible, so that it becomes a part of the definition of the function to specify for each of its bound variables (also called its formal parameters) whether it requires an R-value or an L-value. These alternatives will also be known as calling a parameter by value (R-value) or reference (L-value).

— Christopher Strachey
Fundamental Concepts in Programming Languages, Section 3.4.2

An L-value is the storage location denoted by an expression on the left side of an assignment, and an R-value is the value stored in that location, denoted by an expression on the right side. These lecture notes are a classic of programming language theory and are still cited as the origin of terms such as L-value, R-value, and first-class object.

A practical test for telling the two mechanisms apart fits in one sentence: When a function assigns a new value to its parameter, does the caller’s variable change? If it does, the mechanism is call by reference; if it does not, it is call by value. The test holds under the assumptions of this article: only these two mechanisms are compared, the argument is a reassignable variable, and the parameter can be assigned to. Once other evaluation strategies such as call by copy-restore and call by name come into play, this question alone cannot classify every argument-passing mechanism.

The assignment in this test means putting a different value into the parameter variable itself, as in targetTv = new Tv(). If the parameter points to an object, this makes it point to a different object. Changing the internal state of the object the parameter points to, as in targetTv.setChannel("Rock"), is a separate matter. The misconception discussed later comes from confusing the two.

The Terms "Pass by" and "Call by"

Call by value and call by reference are also called pass by value and pass by reference. The call by ~ form dates back to the ALGOL 60 report published in 1960. Section 4.7.3 of the revised report of 1963 specifies how parameters are passed, with 4.7.3.1 titled "Value assignment (call by value)" and 4.7.3.2 titled "Name replacement (call by name)." The pass by ~ form is also widely used in practice and in textbooks. This article uses call by ~ throughout.

Call by Sharing

The argument-passing behavior of Java, JavaScript, and Python, which shares an object rather than the caller’s variable itself, is sometimes called call by sharing. The term comes from the design document of CLU, a language created in the mid-1970s by a team led by Barbara Liskov. The object-argument behavior of Java, Kotlin, JavaScript, and Python and the passing of class instances in C#, all covered later, fall into this category. The term "call by object reference" used in the Python tutorial means the same thing. The same structure appears when you pass a map or a pointer in Go, or a pointer in C.

"Call by value" can mislead people into thinking the whole object is copied, and "call by reference" can mislead them into thinking that reassignment is reflected in the caller’s variable. Call by sharing is a good term for avoiding both misconceptions. Some sources use it, such as the MDN JavaScript documentation quoted later, but it has not become a standard term in textbooks or language specifications. This article therefore continues with only the two categories of call by value and call by reference.

Java

Result of the swap Method

The output of the following code shows how Java passes arguments.

Testing a swap method

public class ReferenceTest {
    public static void main(String[] args) {
        String x1 = "Hello";
        String y1 = "World";
        swap(x1, y1); // (1)
        System.out.println(x1); // Hello

        int x2 = 1;
        int y2 = 2;
        swap(x2, y2); // (2)
        System.out.println(x2); // 1
    }

    static void swap(Object x, Object y) {
        Object temp = x;
        x = y; // (3)
        y = temp;
    }

    static void swap(int x, int y) {
        int temp = x;
        x = y;
        y = temp;
    }
}

Copies of the reference values held by x1 and y1 are assigned to the parameters x and y.
The int values are copied into the parameters of the swap(int, int) overload. Without this overload, references to autoboxed Integer objects would be passed to the Object parameters, with the same result.
Assigning each other’s values to the parameters x and y inside the method does not change the caller’s x1, y1, x2, or y2.

By the test defined above, Java behaves as call by value for both primitive types and objects.

Why Reassigning a Parameter Does Not Affect the Caller’s Variable

Let’s look more closely at passing an object as a method parameter.

Reassigning a parameter inside a method

class Tv {
    private String channel;

    void setChannel(String channel) { this.channel = channel; }
    String getChannel() { return channel; }
}

public class ReassignTest {
    public static void main(String[] args) {
        var myTv = new Tv();
        myTv.setChannel("Classic");

        reassign(myTv); // (1)
        System.out.println(myTv.getChannel()); // Classic
    }

    static void reassign(Tv targetTv) {
        targetTv = new Tv(); // (2)
        targetTv.setChannel("Rock");
    }
}

The reference value held by myTv in the main method is copied and assigned to the parameter targetTv of the reassign method. The two variables point to the same object, but they are different variables.
A new object is assigned to the parameter targetTv. Only the parameter targetTv now points to the new object, and myTv in the main method still points to the original object. That is why the output is Classic.

Mutating Object State: The Source of the Misconception

If you change the internal state of the object the parameter points to, instead of reassigning the parameter, the changed state is visible through the caller’s variable.

Changing object state inside a method without reassigning the parameter

public class ChangeStateTest {
    public static void main(String[] args) {
        var myTv = new Tv();
        myTv.setChannel("Classic");

        changeState(myTv); // (1)
        System.out.println(myTv.getChannel()); // (3)
    }

    static void changeState(Tv targetTv) {
        targetTv.setChannel("Rock"); // (2)
    }
}

As in the previous example, the reference value held by myTv is copied and assigned to the parameter targetTv of the changeState method. The two variables point to the same object.
Without reassigning the parameter targetTv, the method changes the channel of the object the parameter points to Rock. This is the very object that myTv in the main method points to.
Reading the channel through myTv in the main method prints Rock. The variable did not change, but the state of the object it points to did.

Because the changed state is visible through the caller’s variable, the claim that "objects are passed by call by reference" sounds plausible. As explained above, however, the practical test for the two mechanisms is whether a value assigned to the parameter is reflected in the caller’s variable. The changed state is visible through the caller’s variable only because both variables point to the same object, and what is passed is still a copy of the reference value. In other words, it is call by value.

Head First Java explains object references with the analogy of a TV remote control. Passing an object does not copy the TV (the object); it copies the remote control (the reference value) that operates the TV. If you change the channel with the copied remote (changing object state), the person holding the original remote sees the new channel too. If you pair the copied remote with a new TV (reassignment, targetTv = new Tv()), that remote can no longer operate the original TV, and the original remote is still paired with the original TV.

Java References and Terminology Confusion

James Gosling, the creator of Java, addressed this misconception directly in The Java Programming Language, which he coauthored.

Some people will say incorrectly that objects are passed "by reference." … The Java programming language does not pass objects by reference; it passes object references by value.

— Ken Arnold, James Gosling, David Holmes
The Java Programming Language, 4th edition

Figure 2. Cover of The Java Programming Language, 4th edition (image source: Open Library)

Dev.java, the current official Java learning site, says the same thing.

Reference data type parameters, such as objects, are also passed into methods by value. … when the method returns, the passed-in reference still references the same object as before.

— Dev.java
Calling Methods and Constructors

The Dragon Book quoted earlier also states in the same section that Java uses call by value exclusively. In the call-by-reference entry that follows, however, it writes that Java behaves as if it used call by reference for anything other than basic types.

Even though Java uses call-by-value exclusively, whenever we pass the name of an object to a called procedure, the value received by that procedure is in effect a pointer to the object. Thus, the called procedure is able to affect the value of the object itself. …

As we noted when discussing call-by-value, languages such as Java solve the problem of passing arrays, strings, or other objects by copying only a reference to those objects. The effect is that Java behaves as if it used call-by-reference for anything other than a basic type such as an integer or real.

— Alfred V. Aho, Monica S. Lam, Ravi Sethi, Jeffrey D. Ullman
Compilers: Principles, Techniques, and Tools, 2nd edition, Section 1.6.6

"Behaves as if it used call-by-reference" refers to the effect: the object is not copied as a whole, and changes the called method makes to the object’s state are visible to the caller. The phrase assumes what the book stated earlier, that the actual mechanism is not call by reference.

The word "reference" itself seems to have fed the misconception that Java passes objects by call by reference. Java calls a value that points to an object a "reference," and that word overlaps with the "reference" in "call by reference." Put more precisely, Java passes the reference value that points to an object by call by value.

A Java reference is a value that identifies and gives access to an object. You can think of it as a pointer. The following Java object access

Accessing a Java object

var myTv = new Tv();
myTv.setChannel("Rock");

is similar to this C++ code that uses a pointer.

C++ pointer

Tv *myTv = new Tv();
myTv->setChannel("Rock");

The Java variable myTv holds not the object itself but a value that points to the object. When you pass myTv as an argument to another method, this reference value is copied and passed. The C++ code above is an analogy for object access and pointer reassignment only; it does not mean that object lifetime management or the actual representation of references are the same.

Let’s look at the relevant wording in the JLS (Java Language Specification). The JLS also uses the word "pointer." Section 4.3.1. Objects defines reference values as pointers to objects.

The reference values (often just references) are pointers to these objects, and a special null reference, which refers to no object.

— Java Language Specification
4.3.1. Objects

This describes language-level semantics; it does not guarantee that a reference value has the same format as a raw memory address. JVMS (Java Virtual Machine Specification) 2.7 does not mandate any particular internal structure for objects, and notes that in some implementations a reference may point to a handle rather than to the object data. A handle here is a small intermediate structure between the reference and the object data. The reference points to the handle, and pointers inside the handle in turn point to the object data and the method table. In other words, a reference value may not be the memory address where the object resides.

This description of handles originally described "Sun’s current implementation" in the first edition of the JVMS (1997). The second edition changed the wording to "some of Sun’s implementations," and editions after the Oracle acquisition to "some of Oracle’s implementations," but the content stayed the same. At the time of the first edition, Sun’s JVM was the Classic VM of JDK 1.0 and 1.1, and the "Handleless Objects" section of The Java HotSpot Performance Engine Architecture explains that the Classic VM used indirect handles. According to the same section, HotSpot, which today’s Oracle JDK and OpenJDK share, does not use handles and implements object references as direct pointers to objects.

How arguments are passed in a method call is described in Section 8.4.1. Formal Parameters. It says only that the "values" of the argument expressions initialize newly created parameter variables. Nothing in it says that a parameter becomes an alias of the caller’s variable, as call by reference was defined above.

When the method or constructor is invoked (§15.12), the values of the actual argument expressions initialize newly created parameter variables, each of the declared type, before execution of the body of the method or constructor.

— Java Language Specification
8.4.1. Formal Parameters

A New Frame for Every Method Invocation

The JLS also describes, step by step, how a method invocation is executed. Section 15.12.4.5. Create Frame, Synchronize, Transfer Control says that once the method to invoke has been determined, a new activation frame is created and the argument values are placed in it. An activation frame is a region of memory that holds the execution state of a method call, such as its parameters, local variables, and return address, and that disappears when the call ends.

Now a new activation frame is created, containing the target reference (if any) and the argument values (if any), as well as enough space for the local variables and stack for the method to be invoked … The effect of this is to assign the argument values to corresponding freshly created parameter variables of the method, and to make the target reference available as this, if there is a target reference.

— Java Language Specification
15.12.4.5. Create Frame, Synchronize, Transfer Control

The argument "values" are assigned to parameter variables freshly created in the new frame, not to the caller’s variables. This reaches the same conclusion as Section 8.4.1. The reference to the object on which an instance method is invoked (the target reference) is placed in the new frame in the same way and becomes this.

The JVMS defines this frame at the virtual machine level. Section 2.6. Frames says that a new frame is created on the thread’s JVM stack every time a method is invoked, and that each frame has its own array of local variables.

A new frame is created each time a method is invoked. … Frames are allocated from the Java Virtual Machine stack (§2.5.2) of the thread creating the frame. Each frame has its own array of local variables (§2.6.1), …

— Java Virtual Machine Specification
2.6. Frames

Parameters are passed through this local variable array, as Section 2.6.1. Local Variables explains.

The Java Virtual Machine uses local variables to pass parameters on method invocation. On class method invocation, any parameters are passed in consecutive local variables starting from local variable 0. On instance method invocation, local variable 0 is always used to pass a reference to the object on which the instance method is being invoked (this in the Java programming language). Any parameters are subsequently passed in consecutive local variables starting from local variable 1.

— Java Virtual Machine Specification
2.6.1. Local Variables

Let’s trace how the reference value of myTv in the earlier reassign example is copied into the parameter targetTv within this structure. Two concepts are needed first.

Operand stack: a last-in, first-out stack, one per frame, that serves as the workspace where JVM instructions pop operands and push results. It is also used to prepare the arguments passed to a method.
Bytecode: the JVM instructions that javac compiles Java source into and stores in class files. Two instructions appear in this example’s call sequence.
- aload_1: pushes the reference value held in local variable 1 of the current frame onto the operand stack.
- invokestatic: invokes a static method. It pops the argument values from the operand stack, creates a new frame, and stores those values in the new frame’s local variables starting from local variable 0.

With these concepts, the call to reassign looks like the figure below. Because reassign is a static method, the parameter targetTv is local variable 0 of the reassign frame. The reference value held by myTv, which javac assigned to local variable 1 of the main frame, is copied into this slot. The JVMS dictates that parameters start at slot 0, but the compiler decides which slot each non-parameter local variable occupies. At the bytecode level, the aload_1 instruction pushes this reference value onto the operand stack of the main frame, and the invokestatic instruction pops it and stores it in local variable 0 of the new frame. The two slots are separate storage belonging to different frames, so assigning a new object to targetTv leaves myTv in the main frame pointing to the original object.

Keep in mind that the JVMS defines an abstract machine. It is a model that specifies the rules for how instructions behave, not the memory layout of a particular implementation. The introduction to Chapter 2 of the JVMS leaves the memory layout of run-time data areas to the implementor’s discretion. For example, machine code produced by a JIT compiler may keep parameters in CPU registers. Even so, the language semantics, in which the caller’s variable and the parameter are separate variables, do not change.

Kotlin

Kotlin does not support call by reference either. In Kotlin, however, you cannot even run this article’s test of whether assigning a new value to a parameter changes the caller’s variable. The Function declaration section of the Kotlin Language Specification states that each parameter is introduced as the name of a value inside the function body, so parameters are final and cannot be changed inside the function.

Each parameter p_i: P_i = v_i introduces p_i as a name of value with type P_i available inside function body b; therefore, parameters are final and cannot be changed inside the function.

— Kotlin Language Specification
Function declaration

Code that assigns a new value to a parameter is a compile error.

Reassigning a parameter and changing object state in Kotlin

class Tv(var channel: String)

fun main() {
    val myTv = Tv("Classic")
    changeState(myTv)
    println(myTv.channel) // Rock
}

fun reassign(targetTv: Tv) {
    targetTv = Tv("Rock") // (1)
}

fun changeState(targetTv: Tv) {
    targetTv.channel = "Rock" // (2)
}

This is a compile error with the message "'val' cannot be reassigned."
Changing a property of the object the parameter points to makes the new value visible to the caller. If you delete the reassign function that fails to compile and run the code, it prints Rock.

Apart from reassignment being forbidden, Kotlin behaves like Java. On the JVM, what is passed is a copy of the reference value, as in Java. Because final parameters are part of the language specification, this does not change when you compile to non-JVM platforms such as Kotlin/JS or Kotlin/Native.

JavaScript

JavaScript behaves the same way as Java. Here is the swap example first.

JavaScript swap function

function swap(x, y) {
  const temp = x;
  x = y;
  y = temp;
}

let x1 = "Hello";
let y1 = "World";
swap(x1, y1);
console.log(x1); // Hello

When an object is passed, reassigning the parameter or changing the object’s state inside the function also gives the same results as in Java.

Reassignment and state change when passing an object in JavaScript

const myTv = { channel: "Classic" };

reassign(myTv);
console.log(myTv.channel); // Classic

changeState(myTv);
console.log(myTv.channel); // Rock

function reassign(targetTv) {
  targetTv = { channel: "Rock" }; // (1)
}

function changeState(targetTv) {
  targetTv.channel = "Rock"; // (2)
}

Assigning a new object to the parameter targetTv does not change the caller’s myTv.
Changing a property of the object the parameter points to makes the new value visible through the caller’s myTv.

Replace the Tv object in the two Java figures above with an object literal, and they describe JavaScript’s behavior.

The Functions page on MDN summarizes this behavior in the same terms: arguments are always passed by value, and object arguments are, more precisely, passed by sharing.

Arguments are always passed by value and never passed by reference. This means that if a function reassigns a parameter, the value won’t change outside the function. More precisely, object arguments are passed by sharing, which means if the object’s properties are mutated, the change will impact the outside of the function.

— MDN Web Docs
Functions - Passing arguments

The ECMAScript specification also describes this behavior as initializing new parameter bindings with argument values, not as creating aliases of the caller’s variables. ArgumentListEvaluation obtains values from the argument expressions with GetValue and builds a list of ECMAScript language values, and FunctionDeclarationInstantiation initializes the parameter bindings of the new function environment from that list.

Unlike Java, the ECMAScript specification does not call the value used to access an object a "reference value." Object is one of the eight ECMAScript language types, the kinds of values a program manipulates directly, and an object itself is a value of that type. The "copied reference value" in this article is therefore best understood as a model for explaining the observed behavior.

TypeScript passes arguments the same way as JavaScript. The TypeScript Handbook states that, as a principle, TypeScript does not change the runtime behavior of JavaScript code.

As a principle, TypeScript never changes the runtime behavior of JavaScript code.

— TypeScript Handbook
TypeScript for the New Programmer - Runtime Behavior

After type checking, the TypeScript compiler erases the type information and emits plain JavaScript, so argument passing is identical to the JavaScript behavior described above. TypeScript also has no syntax for reference parameters like C#'s ref and out, which are covered later.

The By Reference Wording in JavaScript: The Definitive Guide

Some sources make it easy to mistake JavaScript function calls for call by reference if you read only part of them. JavaScript: The Definitive Guide, 4th edition, written by David Flanagan and long regarded as the standard JavaScript book, has a summary table in Section 11.2, "By Value Versus by Reference," stating that objects are copied, passed, and compared by reference. From that table alone, it looks as if you could describe JavaScript as call by reference.

Read the explanation of the behavior in the same section, however, and the book’s "by reference" turns out to mean something different from the call by reference defined at the beginning of this article. The book uses the phrase to mean that a reference to the object is passed instead of the whole object value being copied, and it also explains that reassigning the parameter is not reflected in the caller’s variable.

A function can use the reference to modify properties of the object or elements of the array. But if the function overwrites the reference with a reference to a new object or array, that modification is not visible outside of the function. Readers familiar with the other meaning of this term may prefer to say that objects and arrays are passed by value, but the value that is passed is actually a reference rather than the object itself.

— David Flanagan
JavaScript: The Definitive Guide, 4th edition, 11.2 By Value Versus by Reference

The example that follows this explanation is titled "References themselves are passed by value." The observed behavior the book describes is the same as in this article; only the name for what is passed differs.

C

C has no syntax like C++ reference parameters, so it has only call by value. Paragraph 4 of 6.5.2.2 Function calls in the C11 working draft N1570 states that, in preparing a function call, the arguments are evaluated and each parameter is assigned the value of the corresponding argument.

In preparing for the call to a function, the arguments are evaluated, and each parameter is assigned the value of the corresponding argument.

— C11 Working Draft N1570
6.5.2.2 Function calls, paragraph 4

Footnote 93, attached to the same paragraph, explains that a function may change the values of its parameters, but these changes cannot affect the values of the arguments; on the other hand, it is possible to pass a pointer to an object, and the function may then change the value of the object pointed to.

swap implemented with C pointer parameters

void swap(int* x, int* y) {
    int temp = *x;
    *x = *y; // (1)
    *y = temp;
}

int a = 1;
int b = 2;
swap(&a, &b); // (2)

Writing to the variable the pointer points to changes the caller’s a. Assigning a different address to x, however, leaves the caller’s a unchanged.
& is just the address-of operator, and copies of the pointer values are assigned to the parameters x and y. After the call, a is 2 and b is 1.

Applying the test from above, assigning a new value to a pointer parameter does not change the caller’s variable, so this is call by value. It has the same structure as Java passing a reference value to an object.

C++

C++ provides reference parameters, which are call by reference as this article defines it.

swap implemented with C++ reference parameters

void swap(int& x, int& y) { // (1)
    int temp = x;
    x = y; // (2)
    y = temp;
}

int a = 1;
int b = 2;
swap(a, b); // (3)

Declaring the parameter with type int& makes x an alias of the caller’s variable a.
An assignment inside the function actually changes the caller’s variable.
Unlike C’s swap(&a, &b), nothing at the call site indicates that an address is passed. After the call, a is 2 and b is 1.

Pointer Parameters vs. Reference Parameters

C++ also has the pointer parameters (for example, int*) inherited from C, so the two need to be distinguished. Pointer parameters are call by value in C++ too. A function that takes pointers, such as void swap(int* x, int* y), receives copies of the pointer values in its parameters, exactly as in the C example. Assigning a different address to x inside the function is not reflected in the caller’s variable.

An int& reference parameter, on the other hand, has no syntax for reseating it at all. x = y; is not a statement that rebinds the reference to another variable; it assigns a value to the object the reference refers to. Applying the test from above to the two cases gives different results. Assigning to a pointer parameter (int*) leaves the caller’s variable unchanged, while assigning to a reference parameter (int&) changes it.

References in the C++ Standard

The C++ standard also describes a reference as an alias, not as a value that is passed. A note in [dcl.ref] says that a reference can be thought of as "a name of an object." Paragraph 4 of the same section explicitly leaves unspecified whether a reference requires storage.

It is unspecified whether or not a reference requires storage ([basic.stc]).

— C++ Working Draft N4950
[dcl.ref] paragraph 4

Even though compilers usually implement references as addresses, the standard does not even specify whether a reference has storage.

If you judge by what is copied at the machine level, no language would have call by reference at all. The two terms distinguish the semantics a language defines, not the compiled result.

That said, the C++ standard does not call reference parameters call by reference. Searching the entire standard turns up no occurrence of "call by value," "call by reference," or "pass by value," and only four occurrences of "passed by reference," all in notes or library clauses rather than normative definitions. Instead of naming evaluation strategies, the standard specifies behavior. Paragraph 6 of [expr.call] says only that each parameter is initialized with its corresponding argument.

When a function is called, each parameter ([dcl.fct]) is initialized ([dcl.init], [class.copy.ctor]) with its corresponding argument.

— C++ Working Draft N4950
[expr.call] paragraph 6

How a parameter of reference type is initialized is governed separately by the reference binding rules. Call by value and call by reference are not standard terms of any particular language; they are programming language theory terms for comparing argument-passing mechanisms across languages.

C#

Like C++, C# supports call by reference in its syntax. The Method parameters page of the C# reference states that C# passes arguments by value by default, and that a method receives a copy of the value for value types such as structs and a copy of the reference for reference types such as classes.

By default, C# passes arguments to functions by value. This approach passes a copy of the variable to the method. For value (struct) types, the method gets a copy of the value. For reference (class) types, the method gets a copy of the reference.

— C# reference
Method parameters and modifiers

The page goes on to explain that when a reference type is passed by value, reassigning the parameter inside the method does not change the caller’s variable, while changing an instance member is visible through the caller’s variable because both variables refer to the same instance. So far, this is the same as Java.

To pass a parameter by reference, you add the ref, out, in, or ref readonly modifier. Of these, only ref and out allow assigning to the caller’s variable. The same page explains that a parameter passed by reference has no value of its own; it is a reference variable that refers to another variable, the referent. This is call by reference as defined in this article: the parameter becomes an alias of the caller’s variable.

Swap implemented with C# ref parameters

void Swap(ref int x, ref int y) // (1)
{
    int temp = x;
    x = y; // (2)
    y = temp;
}

int a = 1;
int b = 2;
Swap(ref a, ref b); // (3)

The parameter x, declared with the ref modifier, becomes an alias of the caller’s variable a.
Assigning to the parameter changes the caller’s variable.
Unlike C++, the call site also needs ref. After the call, a is 2 and b is 1.

Because a ref parameter requires ref at both the method declaration and the call site, you can tell from the call expression alone that the caller’s variable may change, unlike with C++ reference parameters. out is a variant in which the caller passes an uninitialized variable and the method must assign a value to it, and in and ref readonly are read-only references that the method cannot modify.

ref also works with variables of reference types. Passing a class instance as is copies the reference, as in Java, so reassigning the parameter is not reflected in the caller’s variable. Passing it with ref makes the parameter an alias of the caller’s variable, so reassignment can change which object the caller’s variable points to.

Replacing the caller’s reference-type variable with a C# ref parameter

var myTv = new Tv();
myTv.Channel = "Classic";

Replace(ref myTv); // (1)
Console.WriteLine(myTv.Channel); // Rock

void Replace(ref Tv targetTv)
{
    targetTv = new Tv(); // (2)
    targetTv.Channel = "Rock";
}

class Tv
{
    public string Channel { get; set; } = "";
}

If you declare it as Replace(Tv targetTv) without ref and call Replace(myTv), it behaves like Java’s reassign(myTv) and prints Classic. If the declaration has ref and you omit only the ref at the call site, it is a compile error.
Assigning a new object to the ref parameter makes the caller’s myTv point to the new object. Running it on .NET 8 prints Rock.

C# distinguishes in its syntax between "passing a reference type by value" and "passing a variable by reference with ref," two different behaviors.

Python

Like Java, Python has only call by value. Section 4.8 Defining Functions of the official tutorial explains that arguments are introduced into the local symbol table of the called function, so they are passed using call by value, where the value is always an object reference.

The actual parameters (arguments) to a function call are introduced in the local symbol table of the called function when it is called; thus, arguments are passed using call by value (where the value is always an object reference, not the value of the object).

— The Python Tutorial
4.8 Defining Functions

A footnote on this sentence adds that "call by object reference" would be a better description, because when a mutable object is passed, the caller sees any changes made to it. The Python FAQ answers more directly: arguments are passed by assignment, and since assignment just creates references to objects, there is no alias between an argument name in the caller and in the callee, and so no call by reference.

Python swap function and passing an object

def swap(x, y):
    x, y = y, x  # (1)

a, b = 1, 2
swap(a, b)
print(a)  # 1


class Tv:
    def __init__(self, channel):
        self.channel = channel


def main():
    my_tv = Tv("Classic")
    reassign(my_tv)
    print(my_tv.channel)  # Classic
    changeState(my_tv)
    print(my_tv.channel)  # Rock


def reassign(targetTv):
    targetTv = Tv("Rock")  # (2)


def changeState(targetTv):
    targetTv.channel = "Rock"  # (3)


main()

This only rebinds the local names x and y to different objects, so the caller’s a stays 1.
Rebinding the parameter targetTv to a new object leaves the caller’s my_tv unchanged, and Classic is printed.
Changing an attribute of the object targetTv points to makes the change visible through the caller’s my_tv, and Rock is printed.

The results are the same as Java’s Tv example and JavaScript’s reassign and changeState examples.

Because the caller’s variable stays the same when you pass an integer or a string, but appears changed when you pass a list or a dictionary, it is easy to assume the passing rule depends on the type. The rule is the same. Integers and strings are immutable objects, so there is simply no way to change their internal state. Even with a list, rebinding the parameter inside the function, as in x = [1], leaves the caller unchanged.

Go

Go does not make the caller’s variable an implicit alias of a parameter in a function call either. The Calls section of the Go specification says that after the function value and arguments are evaluated, new storage is allocated for the function’s variables, including its parameters and results, and the arguments are assigned to the corresponding parameters. The Go FAQ answers more directly.

As in all languages in the C family, everything in Go is passed by value. That is, a function always gets a copy of the thing being passed, as if there were an assignment statement assigning the value to the parameter.

— Go FAQ
When are function parameters passed by value?

Taken literally, "all languages in the C family" is not accurate. C++ and C#, covered in this article, belong to the C family but support reference parameters in their syntax. Both languages still pass by value by default, though, and passing by reference is an exception that requires a modifier. The sentence is best read as "the default in C-family languages is pass by value, and Go has only that default." As in C, Go requires you to pass a pointer explicitly to change the caller’s variable.

swap implemented with Go pointer parameters

func swap(x, y *int) {
    *x, *y = *y, *x // (1)
}

a, b := 1, 2
swap(&a, &b) // (2)

Writing to the variables the pointers point to changes the caller’s a and b. Assigning a different pointer to x inside the function does not change the caller’s a.
To change the caller’s values with an ordinary function, you pass pointers as in C. Copies of the pointer values are assigned to the parameters x and y. After the call, a is 2 and b is 1.

Method calls, however, do not need & at the call site. The Calls section of the Go specification states that if x is addressable and the method set of &x contains m, then x.m() is shorthand for (&x).m(). For methods with pointer receivers, the compiler takes the address for you under this rule, so you cannot tell from the shape of the call expression alone whether the caller’s variable may change. Even then, what is passed is a pointer value.

Rust

Rust does not support call by reference in the sense defined in this article, a mechanism in which the parameter becomes an alias of the caller’s variable. Rust by Example calls passing a &T "passed by reference." A function call, however, does not create an alias of the caller’s variable, and a reference such as &mut T is itself a value that is passed by call by value. The Rust Book explains that passing a variable to a function moves or copies the value, just as assignment does.

Passing a variable to a function will move or copy, just as assignment does.

— The Rust Programming Language
4.1 What is Ownership? - Ownership and Functions

To understand "move" in this explanation, you need Rust’s concept of ownership. The Ownership Rules section of the Rust Book summarizes ownership in three rules: each value has a variable that is its owner, there can be only one owner at a time, and when the owner goes out of scope, the value is dropped. An assignment such as let s2 = s1; transfers ownership to s2, which is called a move, and using s1 after the move is a compile error.

Which types are copied is determined by the Copy trait. A trait declares behavior shared by multiple types, similar to an interface in other languages. Some traits have no methods and only tell the compiler about a property of the type; Copy is one of them.

Copy is a trait for types whose original variable remains usable after its value is assigned to another variable. The Stack-Only Data: Copy section of the Rust Book explains that variables of types implementing Copy are not moved but trivially copied, so they remain valid after assignment to another variable. Integers, floating-point numbers, bool, char, and tuples containing only Copy types belong to this group. Types that allocate heap memory or own resources, such as String and Vec, cannot be Copy, and adding Copy to a type that implements Drop, which performs cleanup when a value goes out of scope, is a compile error. In effect, only types that are safe to duplicate bit for bit can be Copy. So in let t = s;, if s is an i32 you can keep using s afterward, but if it is a String it is moved, as shown above.

A value of a non-Copy type such as String has its ownership moved into the parameter, and a value of a Copy type such as i32 is copied. When you pass a variable of type &mut T to a parameter of type &mut T, however, the compiler implicitly reborrows it, so you can use the variable again after the call even though &mut T is not Copy.

From this article’s perspective, moving and copying are the same mechanism, in which the parameter is initialized with the argument value, and neither creates an alias of the caller’s variable. The only difference is whether the caller’s variable remains usable after the call.

swap implemented with Rust mutable references

fn swap(x: &mut i32, y: &mut i32) { // (1)
    let temp = *x;
    *x = *y; // (2)
    *y = temp;
}

let mut a = 1;
let mut b = 2;
swap(&mut a, &mut b); // (3)

What is passed to the parameter x is a value of type &mut i32.
Writing to the variable the mutable reference points to changes the caller’s a.
To change the caller’s values with an ordinary function, you pass mutable references like this. After the call, a is 2 and b is 1.

The standard library function std::mem::swap uses the same approach with the signature fn swap<T>(x: &mut T, y: &mut T). Passing mutable references is still not call by reference as defined in this article, in which reassigning the parameter itself changes the caller’s variable binding. To reassign x, you have to declare the parameter as mut x: &mut i32, and even then the reassignment has no effect on the caller’s a.

Like Go’s pointer-receiver methods, method calls in Rust do not need &mut at the call site. Under the method call rules in the Rust Reference, writing v.push(1) makes the compiler automatically borrow the receiver and pass &mut v, and what is passed is still a mutable reference value.

Ada: Call by Reference vs. Copy-Restore

The definitions section noted that the test "when a function assigns a new value to its parameter, does the caller’s variable change?" cannot classify every passing mechanism by itself. Ada is an example. Ada declares parameters with the modes in, in out, and out, and a value assigned to an in out or out parameter is reflected in the caller’s variable. Judged only by the result the caller observes, this is the same as C++ reference parameters.

Ada Reference Manual 6.2, however, decides whether a parameter is passed by copy or by reference mainly by its type, not its mode. Elementary types such as Integer are by-copy types and are passed by copy; by-reference types such as tagged types are passed by reference; and a formal parameter declared aliased is passed by reference regardless of its type. For parameters that fall into neither category, the manual does not specify whether they are passed by copy or by reference and leaves the choice to the implementation. For in out and out parameters passed by copy, 6.4.1 specifies that their values are copied back to the actual arguments when the subprogram completes normally. This is the call by copy-restore mentioned in the definitions section. The result, a changed caller variable, is the same as with call by reference, but the actual mechanism is copying.

The difference between passing by copy and passing by reference becomes visible when the procedure reads the variable passed as the actual argument directly. The example below passes the same variable Original to a procedure that receives it by copy and to one that receives it as aliased, and reads Original right after assigning to the parameter.

By-copy passing vs. aliased by-reference passing in Ada

with Ada.Text_IO; use Ada.Text_IO;

procedure Demo is
   Original : aliased Integer := 1;

   procedure By_Copy (Param : in out Integer) is
   begin
      Param := 2;
      Put_Line ("inside By_Copy: Original =" & Integer'Image (Original)); -- (1)
   end By_Copy;

   procedure By_Reference (Param : aliased in out Integer) is
   begin
      Param := 2;
      Put_Line ("inside By_Reference: Original =" & Integer'Image (Original)); -- (3)
   end By_Reference;
begin
   By_Copy (Original);
   Put_Line ("after By_Copy: Original =" & Integer'Image (Original)); -- (2)

   Original := 1;
   By_Reference (Original);
   Put_Line ("after By_Reference: Original =" & Integer'Image (Original));
end Demo;

Integer is a by-copy type, so Param is a copy of Original. Right after 2 is assigned to Param, Original is still 1.
When the procedure completes normally, the value of Param is copied back to Original, and Original becomes 2.
An aliased parameter is passed by reference, so Param is an alias of Original. The moment 2 is assigned to Param, Original is 2 as well.

This is the output when compiled with GNAT 13.3, the Ada compiler included in GCC.

Output

inside By_Copy: Original = 1
after By_Copy: Original = 2
inside By_Reference: Original = 2
after By_Reference: Original = 2

After both calls return, the value is 2 in both cases, but reading Original inside the procedures gives different results. A language supporting parameter modes in its syntax and those modes being implemented as call by reference are two separate facts.

Summary

The following table summarizes how the languages covered in this article pass arguments.

Language Supports call by reference Passing mechanism Changing the caller’s variable through a parameter

Language	Supports call by reference	Passing mechanism	Changing the caller’s variable through a parameter
Java	No	Call by value. For objects, a copy of the reference value is passed	Not possible. Only object state changes are shared
Kotlin	No	Call by value. Parameters are final, so reassignment is a compile error	Not possible. Only object state changes are shared
JavaScript	No	Call by value. The Object value is assigned to a separate parameter binding	Not possible. Only object state changes are shared
C	No	Call by value	Pass a pointer (`swap(&a, &b)`)
C++	Yes, only for reference parameters (`int&`)	Call by value by default. Only reference parameters are call by reference	Declare a reference parameter. You can also pass a pointer as in C
C#	Yes, with `ref`, `out`, `in`, and `ref readonly` parameters. Of these, `ref` and `out` allow assigning to the parameter	Call by value by default. For class instances, a copy of the reference is passed	Declare a `ref` or `out` parameter. The call site also needs `ref` or `out`
Python	No	Call by value. The value is always an object reference	Not possible. Only object state changes are shared
Go	No	Call by value. Map and slice values behave like pointers	Pass a pointer (`swap(&a, &b)`). Pointer-receiver methods take the address automatically
Rust	No	Call by value. Depending on the type, the value is moved or copied as in assignment, and a mutable reference `&mut T` is also passed by value	Pass a mutable reference (`swap(&mut a, &mut b)`). Method calls borrow the receiver automatically
Ada	Partially. By-reference types and parameters declared `aliased` are passed by reference regardless of mode. For other types, the manual does not specify. `in out` and `out` parameters of by-copy types are copied back on normal completion (copy-restore)	By copy or by reference, depending on the type	Declare an `in out` or `out` mode

Java

Call by value. For objects, a copy of the reference value is passed

Not possible. Only object state changes are shared

Kotlin

Call by value. Parameters are final, so reassignment is a compile error

Not possible. Only object state changes are shared

JavaScript

Call by value. The Object value is assigned to a separate parameter binding

Not possible. Only object state changes are shared

Call by value

Pass a pointer (swap(&a, &b))

C++

Yes, only for reference parameters (int&)

Call by value by default. Only reference parameters are call by reference

Declare a reference parameter. You can also pass a pointer as in C

Yes, with ref, out, in, and ref readonly parameters. Of these, ref and out allow assigning to the parameter

Call by value by default. For class instances, a copy of the reference is passed

Declare a ref or out parameter. The call site also needs ref or out

Python

Call by value. The value is always an object reference

Not possible. Only object state changes are shared

Call by value. Map and slice values behave like pointers

Pass a pointer (swap(&a, &b)). Pointer-receiver methods take the address automatically

Rust

Call by value. Depending on the type, the value is moved or copied as in assignment, and a mutable reference &mut T is also passed by value

Pass a mutable reference (swap(&mut a, &mut b)). Method calls borrow the receiver automatically

Ada

Partially. By-reference types and parameters declared aliased are passed by reference regardless of mode. For other types, the manual does not specify. in out and out parameters of by-copy types are copied back on normal completion (copy-restore)

By copy or by reference, depending on the type

Declare an in out or out mode

Java, Kotlin, JavaScript, and Python initialize a separate parameter variable or binding with the argument value. They do not support call by reference, in which the caller’s variable itself becomes an alias of the parameter.
- Passing an object neither clones the object nor passes the caller’s variable itself. In Java, the reference value that points to the object, and in JavaScript, the Object value, is passed to a separate parameter, and the caller and callee can observe the same object.
- Reassigning a parameter inside a function does not change the caller’s variable. Changing the internal state of the object the parameter points to, on the other hand, is visible through the caller’s variable. This difference is the source of the misconception that "objects are call by reference."
C and Go pass pointers, and Rust passes mutable references, to change the caller’s values. A call that takes the address or reference of a variable on the spot shows & or &mut, but when you pass a variable that already holds a pointer or reference, or when the compiler takes the address or borrows for you as in Go and Rust method calls, you cannot tell from the shape of the call expression alone. The only languages here in which a parameter becomes an alias of the caller’s variable are C++, C#, and Ada, and Ada sometimes passes by copy and copies back depending on the type.
This object-sharing behavior is sometimes called call by sharing. Some sources, such as JavaScript: The Definitive Guide, 4th edition, describe object sharing as "by reference," but it should be distinguished from call by reference in the sense of passing an alias of the caller’s variable.

References

Terminology
- Alfred V. Aho, Monica S. Lam, Ravi Sethi, Jeffrey D. Ullman, Compilers: Principles, Techniques, and Tools, 2nd edition, Addison-Wesley, 2007, 1.6.6 Parameter Passing Mechanisms
- Christopher Strachey, Fundamental Concepts in Programming Languages, Higher-Order and Symbolic Computation, Vol. 13, 2000, 3.4.2 Parameter calling modes
- Revised Report on the Algorithmic Language Algol 60 - 4.7.3 Semantics
- CLU design document - Call by sharing
Java
- Java Language Specification - 8.4.1. Formal Parameters
- Java Language Specification - 4.3.1. Objects
- Java Language Specification - 15.12.4.5. Create Frame, Synchronize, Transfer Control
- Java Virtual Machine Specification - 2.6. Frames
- Java Virtual Machine Specification - 2.6.1. Local Variables
- Java Virtual Machine Specification - 2.7. Representation of Objects
- Java Virtual Machine Specification (Java SE 6) - 3.7 Representation of Objects
- The Java Virtual Machine Specification, first edition (1997) - 3.7 Representation of Objects (Wayback Machine)
- The Java HotSpot Performance Engine Architecture - Handleless Objects
- Java Virtual Machine Specification - 6.5. invokestatic
- Dev.java - Calling Methods and Constructors
- Ken Arnold, James Gosling, David Holmes, The Java Programming Language, 4th edition, Addison-Wesley, 2006
- Kathy Sierra, Bert Bates, Head First Java, 2nd edition, O’Reilly, 2005, Chapters 3 and 4
Kotlin
- Kotlin Language Specification - Function declaration
JavaScript
- ECMAScript Language Specification - ArgumentListEvaluation
- ECMAScript Language Specification - FunctionDeclarationInstantiation
- MDN Web Docs - Functions, Passing arguments
- TypeScript Handbook - TypeScript for the New Programmer, Runtime Behavior
- David Flanagan, JavaScript: The Definitive Guide, 4th edition, O’Reilly, 2001, 11.2 By Value Versus by Reference
C
- C11 Working Draft N1570 - 6.5.2.2 Function calls
C++
- C++ Working Draft N4950 - [dcl.ref] References
- C++ Working Draft N4950 - [expr.call] Function call
C#
- C# Reference - Reference parameters
Python
- The Python Tutorial - 4.8 Defining Functions
- Python Programming FAQ - How do I write a function with output parameters (call by reference)?
Go
- The Go Programming Language Specification - Calls
- Go FAQ - When are function parameters passed by value?
Rust
Ada
- Ada Reference Manual - 6.2 Formal Parameter Modes
- Ada Reference Manual - 6.4 Subprogram Calls, 6.4.1 Parameter Associations

VO vs. DTO: Definitions and the History of Conflating the Terms

Sat, 3 Oct 2026 00:00:00 +0000

Table of Contents

Definition of Value Object
- The Status of Immutability: Definitional Requirement vs. Good Design
Definition of DTO (Data Transfer Object)
VO in the First Edition of Core J2EE Patterns and TO in the Second
The Cost of Calling a Data Carrier a VO
References
- Value Object
- Transfer Object / DTO

In practice, you often come across objects with nothing but getters and setters, whose job is to carry values, being called VOs (Value Objects). If the object’s role is to carry data across a remote call between processes, calling it a DTO (Data Transfer Object) leaves less room for confusion. Value Object is a term that Martin Fowler’s writing and Eric Evans’s DDD (Domain-Driven Design) have already defined with a different meaning. This article lays out the definitions of the two patterns and the history of how the terms got mixed up.

Definition of Value Object

A Value Object is an object that has no identity and whose equality is determined by the values it holds.

Identity is the property that distinguishes one object from another regardless of its attribute values. A member is still the same member after their name or address changes, and two members with the same name and address are still different people. Such objects are distinguished by an identifier like a member number, and DDD calls them ENTITIES.

Equality is the criterion for deciding whether two objects count as the same. A Value Object bases this criterion on the values it holds rather than on an identifier. Concepts like money, color, and date are typical examples. For instance, Instant in Java, which represents a point on the timeline, compares equal with equals() when two instances refer to the same instant, even if they were created separately by different means.

Instant fromText = Instant.parse("2026-09-24T20:00:00Z");
Instant fromSeoulTime = ZonedDateTime.of(2026, 9, 25, 5, 0, 0, 0, ZoneId.of("Asia/Seoul"))
    .toInstant();

assertThat(fromText).isEqualTo(fromSeoulTime); // 20:00 on the 24th UTC and 05:00 on the 25th in Seoul are the same instant

This definition can be confirmed in the three sources below.

Martin Fowler’s article: objects regarded as equal because their attribute values are equal. He explains this using a point made up of x and y coordinates as the example.

Objects that are equal due to the value of their properties, in this case their x and y coordinates, are called value objects.
Wikipedia: an object whose equality is not based on identity, and which counts as the same when it holds the same values
Microsoft’s .NET architecture documentation: an object with no identity

Eric Evans takes the same view. In the Value Objects entry of the Domain-Driven Design Reference (2015), which Evans published as a summary of the pattern definitions in Domain-Driven Design, the problem statement presupposes that many objects have no conceptual identity, and it says to classify a model element as a value object when you care only about its attributes and logic.

Some objects describe or compute some characteristic of a thing. Many objects have no conceptual identity. …

Therefore:

When you care only about the attributes and logic of an element of the model, classify it as a value object. Make it express the meaning of the attributes it conveys and give it related functionality.

— Eric Evans
Domain-Driven Design Reference: Value Objects

In Java code, a class that expresses a value concept becomes a Value Object when it implements equals() and hashCode() on the attributes that serve as the criterion for equality. The contracts of these two methods that must be honored are laid out in Item 10 and Item 11 of Joshua Bloch’s Effective Java, 3rd ed.

Item 10: the general contract of equals()
- Reflexive: x.equals(x) returns true.
- Symmetric: if x.equals(y) returns true, then y.equals(x) also returns true.
- Transitive: if x.equals(y) and y.equals(z) return true, then x.equals(z) also returns true.
- Consistent: as long as the information used in the comparison does not change, x.equals(y) returns the same result no matter how many times it is called.
- Non-null: x.equals(null) returns false.
Item 11: when you override equals(), also override hashCode()
- As long as the information used in equals() comparisons does not change, hashCode() returns the same value no matter how many times it is called.
- Two objects that are equal according to equals() return the same hashCode() value.
- Two objects that are unequal according to equals() are not required to return different hashCode() values, but returning different values improves the performance of hash tables.

With records, which became a standard feature in Java 16, you no longer have to write these two methods yourself. JEP 395, which introduced records, states that a record’s equals() and hashCode() are generated automatically based on the values of all its components. Two record instances are equal when they have the same type and all of their component values are equal.

public record Money(BigDecimal amount, Currency currency) {
}

Two instances of this class are equal when the values they hold are the same.

Currency krw = Currency.getInstance("KRW");
Money price1 = new Money(BigDecimal.valueOf(10000), krw);
Money price2 = new Money(BigDecimal.valueOf(10000), krw);

assertThat(price1).isEqualTo(price2); // equal when the values match, even with different references

However, because a record uses the equals() of each component type as is, the automatically generated equality may differ from the equality the domain wants. For example, BigDecimal’s `equals() compares the scale as well, so Money instances created from new BigDecimal("10000") and new BigDecimal("10000.0") end up as different values. In such cases, normalize the values in the constructor or define equals() yourself.

The concept of an identity-free value object is also being introduced into the Java language and the JVM. It shares with the Value Object of DDD and Fowler the trait of being distinguished by value, without identity. Project Valhalla’s JEP 401: Value Objects (Preview) proposes value objects that are immutable, have no object identity, and are distinguished only by their field values. As of August 2026, this JEP has been integrated as a preview feature into JDK 28, scheduled for release in March 2027. JEP 169: Larval State for Value Objects is a separate Draft proposal that deals with a temporary mutable state for these immutable value objects. That said, identity in DDD is a question of whether something needs to be conceptually distinguished in the domain, while the identity that Valhalla removes is a runtime property by which the JVM tells objects apart, so the two value objects are not the same concept. Even so, neither side uses value object to mean an object with nothing but getters and setters.

Meanwhile, in practice, a convention has also spread that interprets VO in the broad sense of a data holder, independent of the definition above, and calls carrier objects with nothing but getters and setters VOs. The main source that spread this convention is examined in the Core J2EE Patterns section below.

The Status of Immutability: Definitional Requirement vs. Good Design

Many books and articles recommend making Value Objects completely immutable.

On p. 486 of Patterns of Enterprise Application Architecture, Fowler recommends making Value Objects immutable, saying "it’s a very good idea to make them immutable".
Fowler’s Value Object article says the same. The version before the 2016 revision presented making value objects entirely immutable as a general heuristic, and the current revised version also presents "value objects should be immutable" as an important rule.

A general heuristic is that value objects should be entirely immutable.
In the Value Objects entry of the DDD Reference quoted above, Eric Evans gives the design guideline to treat value objects as immutable.

Treat the value object as immutable. Make all operations Side-effect-free Functions that don’t depend on any mutable state. Don’t give a value object any identity and avoid the design complexities necessary to maintain entities.
In Item 17 "Minimize mutability" of Effective Java, 3rd ed., Joshua Bloch recommends, for classes in general and not just Value Objects, minimizing mutability and making them immutable where possible.

If a VO is immutable, no aliasing bug arises even when several objects share the same instance. An aliasing bug is the problem where changing a value on one side also changes the value on another side that references the same instance. Java’s java.util.Date and Calendar are objects with the nature of values, yet they were designed to be mutable and became a source of such bugs. For example, when two objects share a single Date instance holding a meeting’s start time, calling setTime() on one side changes the start time on the other side as well.

Side effect of the mutable Date class

record Meeting(String title, Date start) {
}

Date start = new Date();
Meeting review = new Meeting("Design review", start);
Meeting retro = new Meeting("Retrospective", start);

long oneHourLater = start.getTime() + Duration.ofHours(1).toMillis();
review.start().setTime(oneHourLater); // (1)

assertThat(retro.start().getTime()).isEqualTo(oneHourLater); // (2)

Tries to postpone only the design review by one hour
The retrospective’s start time changes too

Declaring Meeting as a record is not enough on its own to prevent this problem. A record only prevents assigning a different instance to a field; the internal state of the Date that the field references can still be changed.

The fact that Java 8’s java.time package made all of its date and time classes, such as LocalDate and Instant, immutable also reflects this lesson. If the start time is represented as a LocalDateTime, a date and time without a time zone, plusHours() returns a new instance instead of modifying the existing one, so sharing the instance does not change the start time of the other meeting.

record Meeting(String title, LocalDateTime start) {
}

LocalDateTime start = LocalDateTime.of(2026, 9, 25, 14, 0);
Meeting review = new Meeting("Design review", start);
Meeting retro = new Meeting("Retrospective", start);

Meeting delayedReview = new Meeting(review.title(), review.start().plusHours(1));

assertThat(delayedReview.start()).isEqualTo(LocalDateTime.of(2026, 9, 25, 15, 0));
assertThat(retro.start()).isEqualTo(start); // (1)

The retrospective’s start time is unchanged

A close look at Fowler’s and Evans’s sentences, however, shows that immutability appears as a guideline, not as the definition of a VO. Fowler presents immutability as a rule for avoiding aliasing bugs, and Evans presents it as an imperative design guideline. The property Fowler presents as the definition of a Value Object is equality by value. The "value objects should be immutable" quoted above also appears, when you read the whole sentence, as a rule he follows in order to avoid aliasing bugs.

To avoid aliasing bugs I follow a simple but important rule: value objects should be immutable.

— Martin Fowler
Value Object

In the same article, he even mentions an alternative: aliasing bugs can also be avoided when the language copies the value on every assignment, as with structs in C#.

While immutability is my favorite technique to avoid aliasing bugs, it’s also possible to avoid them by ensuring assignments always make a copy. Some languages provide this ability, such as structs in C#.

— Martin Fowler
Value Object

Evans wrote about immutability in imperative sentences. In the solution part of the DDD Reference quoted above, the criterion for classifying something as a value object is whether you care only about the attributes and logic of the model element. The "Treat the value object as immutable." that follows is an imperative sentence telling you to treat the objects so classified as immutable, and the sentence right after it is also an imperative, telling you to make all operations side-effect-free functions. I read these sentences not as classification criteria but as design guidance for handling the objects once they have been classified.

The comments Fowler left on the ValueObjectsShouldBeImmutable page of Ward Cunningham’s wiki show the distinction between definition and guideline even more clearly. He says not to give a newly designed object any methods that change its state.

So if you design an object that should be a value object, don’t provide any methods that change its state, ie make it immutable.

— Martin Fowler
c2 wiki: ValueObjectsShouldBeImmutable

And about Value Objects that have already been made mutable, he says the following.

If you are using a ValueObject that is mutable, treat it like it is immutable. You may not realize why, but you will save a lot of time and money.

— Martin Fowler
c2 wiki: ValueObjectsShouldBeImmutable

The very premise "If you are using a ValueObject that is mutable" presupposes the existence of Value Objects that are not immutable. The page is also named ShouldBeImmutable, not MustBeImmutable. The Cambridge Dictionary gives the first meaning of should as follows.

used to say or ask what is the correct or best thing to do

— Cambridge Dictionary
should

The same dictionary explains must as used to show that it is necessary or very important that something happens. If must expresses a necessity that something has to be so, should expresses a recommendation that doing so is the right thing.

On the other hand, some sources do describe immutability as part of the definition.

Microsoft’s .NET architecture documentation mentioned above lists the absence of identity and immutability side by side as the two main characteristics of value objects, and states that immutability is an important requirement.

There are two main characteristics for value objects: They have no identity. They are immutable. The first characteristic was already discussed. Immutability is an important requirement.
Wikipedia writes that value objects should be immutable, and explains that immutability is required for the implicit contract that two value objects created with the same values must remain equal. Although it uses should, it treats immutability as the premise of a contract, which gives it a status close to that of a definition.
Chapter 6 of Vaughn Vernon’s Implementing Domain-Driven Design (2013) also includes immutability as one of the characteristics it lists for Value Objects.
Kim Woo-geun’s Pragmatic Programming for Java/Spring Developers (2024, in Korean) also explains that "A VO is an object that has this property of immutability" (p. 43), and defines a VO as an object that satisfies three characteristics: immutability, equality, and self-validation.
There are also concepts like the value object of JEP 401, where fields implicitly become final and shallow immutability is enforced at the language level. A different instance cannot be assigned to a field, but the internal state of the object a field references does not thereby become immutable.

I see immutability as a desirable design norm rather than a definitional requirement of a VO. On the c2 wiki, Fowler too wrote that newly designed objects should be made immutable. Since a new Value Object is designed to be immutable whichever view you follow, cases where the difference between should and must shows up in practice are not common. Still, the distinction is not meaningless. When you meet a value-like object that was built mutable, like java.util.Date, including immutability in the definition makes that object something other than a VO, while treating immutability as a guideline makes it a VO that fails to follow the immutability guideline. Fowler’s sentence on the c2 wiki is practical advice from the latter viewpoint. It means that if you have already run into a VO that fails the immutability guideline, you should at least treat it as if it were immutable instead of excluding it as not a VO.

It is similar to the difference between including 'not driving after drinking' in the definition of a driver and seeing it as a norm a driver must follow. Either way, the conclusion that you must not drive after drinking is the same, but if the norm is folded into the definition, there is no longer a name for the violations that exist in reality, which makes such cases hard to discuss.

Definition of DTO (Data Transfer Object)

In Fowler’s original definition, a DTO is an object meant to reduce the cost of remote calls. The catalog for Martin Fowler’s Patterns of Enterprise Application Architecture defines a DTO as follows.

An object that carries data between processes in order to reduce the number of method calls.

— Martin Fowler
Patterns of Enterprise Application Architecture catalog: Data Transfer Object

The same definition appears on page 401 of the book. Every remote call costs a network round trip and serialization, so the pattern grew out of the intent to deliver all the needed data in a single call. For example, instead of fetching a customer’s name, address, and order list with three remote getter calls, you receive a single DTO holding all three values in one call.

Objects that hold data crossing the network, such as HTTP API requests and responses, fit this definition in that they cross a process boundary and are serialized. Not every HTTP API is designed to reduce the number of remote calls, however, so calling these objects DTOs extends the original definition to modern API boundaries.

In practice the definition has been stretched further. A convention has emerged of calling any object that carries data across layer boundaries within the same process a DTO, with no remote call involved. Examples include objects holding DB query results, objects passed from the service layer to the view rendering layer, and response-only objects converted from JPA entities so that the entities are not exposed directly outside the service layer. This usage is far from the original definition of reducing the number of remote calls, so one could argue that such objects are hard to call DTOs.

Apart from the debate over the name, one can also ask whether having such objects in a local context is desirable from a design standpoint. In LocalDTO, Fowler takes issue not with the name but with this usage. His starting point is that the DTO pattern exists to reduce the cost of remote calls, so in a local context with no remote calls that reason disappears. He therefore says that in a local context DTOs are not just unnecessary but actually harmful. The reasons are that a coarse-grained API that exchanges a lot of data in a single call is awkward to use, and that all the work of moving data from the domain layer or data source layer into DTOs is added cost.

Not just do you not need them in a local context, they are actually harmful both because a coarse-grained API is more difficult to use and because you have to do all the work moving data from your domain or data source layer into the DTOs.

— Martin Fowler
LocalDTO

To the argument that DTOs should be placed in the service layer API so that the service layer’s clients do not depend on the domain model, he replies that this may be convenient but is not worth all the cost of the data mapping.

In the same article, however, he acknowledges that something like a DTO is useful even locally when there is a large gap between the presentation layer’s model and the domain model.

One case where it is useful to use something like a DTO is when you have a significant mismatch between the model in your presentation layer and the underlying domain model.

— Martin Fowler
LocalDTO

In such cases the mapping between the two models is needed anyway, so the DTO is not an added cost. Later in the same article he also adds the use of DTOs for exchanging data as messages between isolated areas in a multithreaded application. In short, Fowler’s criticism is aimed at DTOs introduced for the sake of separation from the domain model itself. It does not reject cases where there is a real need, such as a mismatch between models or message passing between isolated areas.

The naming debate and the usage debate are different questions, but they start from the same premise. The fact that a local context has no remote calls serves, on one side, as grounds that the name DTO does not match the original definition, and on the other, as grounds that the reason to have a DTO grows weak. The role-based suffixes I propose later are an answer to the naming debate. Whether to have such an object at all is a matter to settle separately in the usage debate, and if you decide to have one, the proposal is to give it a name that reveals its role rather than Dto.

In the end, the criterion for distinguishing a VO from a DTO is the object’s characteristics and role. Representing a value concept and judging equality by value is a property of a VO; carrying data across a boundary is the role of a DTO. The two are not mutually exclusive categories. An immutable DTO with value equality is also a VO. Conversely, not every DTO needs value equality.

VO in the First Edition of Core J2EE Patterns and TO in the Second

In the Java/J2EE (now Jakarta EE) community, a prominent early source that spread the conflation of the two terms is Core J2EE Patterns: Best Practices and Design Strategies by Deepak Alur and others. The first edition, published in 2001, defined an object that transfers data between tiers as a pattern named Value Object. The second edition in 2003 renamed the same pattern TO (Transfer Object). The rename appears intended to avoid confusion with the Value Object as a value-equality object. Martin Fowler calls the pattern with the same role a DTO (Patterns of Enterprise Application Architecture, p. 401). In short, the following three refer to the same transfer pattern.

VO in Core J2EE Patterns 1st ed. = TO in the 2nd ed. = Martin Fowler’s DTO

Oracle’s Transfer Object documentation describes this pattern under the renamed name, Transfer Object.

Several other books also wrote that VO and DTO mean the same thing or are very close concepts.

Rod Johnson, Expert One-on-One J2EE Design and Development, Wrox, 2002, p. 265

Value objects are sometimes referred to as Data Transfer Objects (DTOs).
Rod Johnson and Juergen Hoeller, Expert One-on-One J2EE Development without EJB, Wrox, 2004, p. 27

Transfer objects, often referred to as Data Transfer Objects (DTOs) or Value Objects.
Murat Yener and Alex Theedom, Professional Java EE Design Patterns, Wrox, 2014, Chapter 12

The DTO is also referred to as the Value Object
Derek C. Ashmore, The Java EE Architect’s Handbook, Second Edition, DVT Press, 2014, Chapter 5

My definition of 'value object' is very close to a Data Transfer Object (DTO)

I cannot say for certain that all of these books were directly influenced by the first edition of Core J2EE Patterns. But given when they appeared and the phrasing repeated across the literature, I suspect the first edition’s usage had some influence on the wording of later Java/J2EE literature. More than twenty years after the second edition changed the name, the practice remains.

The Cost of Calling a Data Carrier a VO

You might wonder whether a name already in common use within a team really needs to change. But the practice of calling data carrier objects VOs has a real cost, because the Value Object as a value-equality object keeps appearing in three contexts: DDD, ORM, and Java language and JVM features.

DDD (Domain-Driven Design): the VALUE OBJECT is, along with the ENTITY, a core building block of the domain model. An AGGREGATE is a consistency boundary for data changes with a single ENTITY as its root, and it can contain other ENTITIES and VALUE OBJECTS inside it.
ORM: @Embeddable in Hibernate and JPA maps an object that has no persistent identity of its own and belongs to the entity that owns it. It is the structure commonly used to map DDD VALUE OBJECTS, but JPA does not enforce value equality or immutability, so not every @Embeddable is a DDD VALUE OBJECT.
Java language and JVM features: the Project Valhalla documents, including JEP 401, use the term value object to mean an object that is immutable, has no object identity, and is distinguished by its field values.

If you understand a VO as a data holder with nothing but getters and setters, the terminology clashes when you read these materials, and confusion follows. For example, reading an explanation that says to map a VO as an @Embeddable, you picture a request parameter object full of setters. Calling a data carrier object that crosses a remote process boundary a DTO connects naturally both with Fowler’s definition and with the renamed name used since the second edition of Core J2EE Patterns.

As seen in the DTO definition section above, recent convention also uses DTO in the broad sense of a data holder that crosses a layer boundary. But attaching the DTO suffix to every carrier object has a drawback. If objects holding HTTP request parameters and objects holding the results of statistics queries are all called DTOs, the name alone does not reveal the role. For example, from the name IssueDto alone you cannot tell whether it is a request body, a lookup response, or the result of a statistics query.

I recommend dividing suffixes by the object’s role. The name then reveals the role on its own, and you also avoid the debate over departing from the strict definition when objects used in layers unrelated to remote calls are called DTOs. Here are some example names.

Role Example class names

Role	Example class names
JSON response for an issue lookup	`IssueResponse`, `IssueDetailDto`
JSON request for issue creation	`IssueCreationRequest`, `IssueCreationCommand`
Issue lookup criteria	`IssueQuery`, `IssueCriteria`
Result of an issue statistics query against the DB	`IssueStatsRow`

JSON response for an issue lookup

IssueResponse, IssueDetailDto

JSON request for issue creation

IssueCreationRequest, IssueCreationCommand

Issue lookup criteria

IssueQuery, IssueCriteria

Result of an issue statistics query against the DB

IssueStatsRow

References

Value Object

Martin Fowler: Value Object
Martin Fowler: Value Object (version before the 2016 revision, Wayback Machine)
C2 Wiki: Value Objects Should Be Immutable
Wikipedia: Value object
Microsoft: Implement value objects
Martin Fowler, Patterns of Enterprise Application Architecture, Addison-Wesley, 2002, p. 486
Eric Evans, Domain-Driven Design, Addison-Wesley, 2003
Eric Evans: Domain-Driven Design Reference (2015), Value Objects
Kim Woo-geun, Pragmatic Programming for Java/Spring Developers (in Korean), WikiBooks, 2024, p. 43
Joshua Bloch, Effective Java 3rd ed., Addison-Wesley, 2018, Items 10, 11, and 17
Vaughn Vernon, Implementing Domain-Driven Design, Addison-Wesley, 2013, Chapter 6
Ward Cunningham: The CHECKS Pattern Language of Information Integrity - Whole Value
JEP 395: Records
JEP 401: Value Objects (Preview)
JEP 169: Larval State for Value Objects

Transfer Object / DTO

Martin Fowler: Data Transfer Object
Martin Fowler: LocalDTO
Martin Fowler, Patterns of Enterprise Application Architecture, Addison-Wesley, 2002, p. 401
Deepak Alur, John Crupi, and Dan Malks, Core J2EE Patterns: Best Practices and Design Strategies 1st ed., Prentice Hall, 2001
Rod Johnson, Expert One-on-One J2EE Design and Development, Wrox, 2002, p. 265
Rod Johnson and Juergen Hoeller, Expert One-on-One J2EE Development without EJB, Wrox, 2004, p. 27
Murat Yener and Alex Theedom, Professional Java EE Design Patterns, Wrox, 2014, Chapter 12
Derek C. Ashmore, The Java EE Architect’s Handbook, Second Edition, DVT Press, 2014, Chapter 5
Oracle: Core J2EE Patterns - Transfer Object
Adam Bien: Value Object vs. Data Transfer Object (VO vs. DTO)

Documenting and Verifying Thread Safety: Javadoc, Annotations, Static Analysis, and ArchUnit

Sat, 3 Oct 2026 00:00:00 +0000

Table of Contents

Thread Safety in Javadoc
Thread Safety with Annotations
What Static Analysis Tools Check
Project-Specific Rules Verified with ArchUnit
- Example Code
- Rules and Results
Summary
References

Whether instances of a class can be shared by multiple threads is information developers need to check carefully. Yet the standard Javadoc tags (@param, @return, @throws, and so on) include no tag for thread safety. As a result, users of a class can easily miss what its provider intended. This article first looks at a good classification scheme for stating thread safety in Javadoc. It then covers how to use annotations, static analysis tools, and ArchUnit tests to keep code that is unsafe under multiple threads from being deployed.

Thread Safety in Javadoc

This section covers four topics in order:

Why Javadoc does not show synchronized on methods
Why a class-level statement is still needed
A suitable classification for documentation
Examples from real library documentation

Why Javadoc Hides synchronized

When an instance method carries the synchronized keyword, the instance itself becomes the lock. Even if several threads call synchronized methods on the same instance at the same time, only one thread can enter. The others wait until the first thread leaves the method. A static synchronized method uses the Class object of its class as the lock. So synchronized is a clue to thread safety, and it would seem useful to show it in Javadoc. Javadoc, however, does not print the synchronized keyword in method declarations. Synchronization is considered an implementation detail, not a contract to expose in the API documentation. Item 82 of Effective Java, Third Edition, defends this policy on the same grounds.

synchronized on a method declaration is equivalent to wrapping the whole method body in a synchronized(this) block. That is, the following code

synchronized on the method declaration

synchronized void run() {
    // do something
}

does the same thing as this code:

The whole method body in a synchronized block

void run() {
    synchronized (this) {
        // do something
    }
}

As the implementation improves, the synchronized region may shrink to part of the method, or a separate lock object may replace this. Such implementation details change more often than the external interface. It is also hard to show every lock-protected region in the method declaration. Some classes synchronize internally with java.util.concurrent.locks.Lock or CAS (Compare And Swap) operations. The presence or absence of the synchronized keyword therefore cannot be the only criterion for thread safety.

The Need for a Class-Level Thread Safety Statement

In a multithreaded environment, each method call may be safe on its own while a combination of calls is not. For example, a HashMap that is safely published after construction (for instance, through a final field or a volatile variable) and never modified afterward can be read with get() from several threads without problems. But if one thread changes its structure with put() while another calls get(), the result is not guaranteed. The same applies to Hashtable, whose public methods are all synchronized or delegate to synchronized methods and views, and to a Map wrapped with Collections.synchronizedMap(). When two calls are combined, such as checking with containsKey() and then calling put(), a race condition occurs unless the caller holds a lock externally.

What needs documenting, then, is not whether methods are synchronized but under what conditions the class is safe. Since Javadoc has no convention for this, developers have to write it in the class description themselves. The Effective Java classification in the next section provides the criteria.

The Five Levels of Thread Safety in Effective Java

Item 82 of Effective Java, Third Edition, "Document thread safety" (Item 70 in the Second Edition), recommends documenting thread safety in five levels.

Immutable
- The state never changes, so no external synchronization is needed.
- Examples: String, Long, BigInteger (the book’s examples), java.time.LocalDate
Unconditionally thread-safe
- The class has mutable state but synchronizes sufficiently inside.
- Examples: AtomicLong, ConcurrentHashMap
Conditionally thread-safe
- Some methods require external synchronization to be safe.
- Example: a List wrapped with Collections.synchronizedList(). While iterating with an iterator, the caller must hold the List object as a lock. Otherwise, the behavior is non-deterministic. A fail-fast iterator may throw ConcurrentModificationException, but there is no guarantee that it will.
Not thread-safe
- The caller must synchronize externally.
- Examples: HashMap, ArrayList
Thread-hostile
- The class cannot be used by multiple threads even with external synchronization. Classes or methods that modify static data without synchronization fall into this category. Even if each caller locks a different instance, they all end up modifying the same static data concurrently.
- Examples: The Third Edition explains that the generateSerialNumber method in Item 78 would be thread-hostile if it incremented a static field without internal synchronization. System.runFinalizersOnExit(), the example in the Second Edition, was deprecated in JDK 1.2 and removed in JDK 11.

Examples in Class Descriptions

Here are three examples of where and how the Java standard library and Spring Batch describe thread safety.

java.util.LinkedList

The JDK 25 Javadoc for LinkedList states in bold, in the third paragraph of the class description, that it is "not synchronized".

java.text.SimpleDateFormat

The JDK 25 Javadoc for SimpleDateFormat has a final section of the class description titled "Synchronization", which says "Date formats are not synchronized". Its "API Note" recommends DateTimeFormatter as an "immutable and thread-safe alternative".

The JDK 25 Javadoc for DateTimeFormatter states "This class is immutable and thread-safe." under "Implementation Requirements" at the end of the class description.

The java.time package, added in JDK 8, applies this format across the whole package. In the JDK 25 source, 31 of the 43 public classes in java.time and its subpackages, including LocalDate, Instant, and ZonedDateTime, state the same sentence in the same place with the Javadoc @implSpec tag. All 12 public enums also use a sentence of the same shape, such as "This is an immutable and thread-safe enum." Of the remaining 12 classes, all but the utility class TemporalQueries state their immutability or threading conditions in the same section. Exception classes, for example, say "This class is intended for use in a single thread."

That said, this format has not become a standard across the whole JDK. @implSpec is not a standard Javadoc tag. It is a JDK-specific tag registered with the -tag option when the JDK is built. If you use it as is in an ordinary project, the JDK 25 javadoc command reports the error "unknown tag. Unregistered custom tag?". Within the JDK, new APIs also differ. Arena and Linker in java.lang.foreign, which became a final API in JDK 22, and ListFormat, added in JDK 22, state thread safety in @implSpec. In contrast, HexFormat, added in JDK 17, writes the same sentence "This class is immutable and thread-safe." in the body without @implSpec, and HttpClient, added in JDK 11, also says in the body "Once built, an HttpClient is immutable".

org.springframework.batch.item.file.FlatFileItemWriter

The FlatFileItemWriter Javadoc in Spring Batch 5.2.6 states on the last line of the class description "The implementation is not thread-safe.", with only "not" in bold.

As these examples show, each class marks thread safety in a different place and a different way. LinkedList and FlatFileItemWriter use bold text, and SimpleDateFormat uses a separate section heading. All four classes, however, put the statement in the middle or at the end of the class description rather than in the first paragraph, so anyone who does not read the API documentation to the end can easily miss it. I find myself wishing for a rule such as "Put thread safety on the first line of the class description, and always make it stand out."

Thread Safety with Annotations

Marking thread safety with annotations instead of prose gives it a consistent place and format in Javadoc. When an annotation’s declaration carries the @Documented meta-annotation, Javadoc prints that annotation as is in the class declaration. We first look at a project that defined its own annotation for this purpose, and then at annotations that many projects can share.

@Contract in Apache HttpClient

Apache HttpClient 5 defines a single annotation for thread safety, org.apache.hc.core5.annotation.Contract. Its threading attribute takes a value of the ThreadingBehavior enum.

ThreadingBehavior Meaning

ThreadingBehavior	Meaning
`IMMUTABLE`	Fully immutable and thread-safe.
`IMMUTABLE_CONDITIONAL`	Immutable if the dependencies injected through the constructor are immutable, and thread-safe if they are thread-safe.
`STATELESS`	Stateless and thread-safe.
`SAFE`	Thread-safe.
`SAFE_CONDITIONAL`	Thread-safe only if the dependencies injected through the constructor are thread-safe.
`UNSAFE`	Not thread-safe. This is the default when the `threading` attribute is omitted.

IMMUTABLE

Fully immutable and thread-safe.

IMMUTABLE_CONDITIONAL

Immutable if the dependencies injected through the constructor are immutable, and thread-safe if they are thread-safe.

STATELESS

Stateless and thread-safe.

SAFE

Thread-safe.

SAFE_CONDITIONAL

Thread-safe only if the dependencies injected through the constructor are thread-safe.

UNSAFE

Not thread-safe. This is the default when the threading attribute is omitted.

In the HttpClient 5.5 source, the main classes are declared as follows.

HttpClient 5.5

@Contract(threading = ThreadingBehavior.SAFE)
public abstract class CloseableHttpClient implements HttpClient, ModalCloseable {

@Contract(threading = ThreadingBehavior.SAFE_CONDITIONAL)
public class PoolingHttpClientConnectionManager
        implements HttpClientConnectionManager, ConnPoolControl<HttpRoute> {

@Contract(threading = ThreadingBehavior.SAFE)
public class BasicHttpClientConnectionManager implements HttpClientConnectionManager {

SAFE_CONDITIONAL has a name similar to "conditionally thread-safe" in Effective Java, but it means something different. The Effective Java classification is about which sequences of method calls need external synchronization, while the HttpClient value is about whether the dependencies received through the constructor are thread-safe.

@Contract carries the @Documented meta-annotation, so it appears in the class declaration in Javadoc. Below is the Javadoc for BasicHttpClientConnectionManager.

Because it always appears in the same place, thread safety is visible at a glance. The class description also says "this class is fully thread-safe", but the annotation in the declaration catches the eye first.

HttpClient did not start with its own annotation. Up to HttpClient 4.5.2, HttpGet and the classes from the 5.5 example above were declared with @NotThreadSafe and @ThreadSafe, as shown below.

HttpClient 4.5.2

@NotThreadSafe
public class HttpGet extends HttpRequestBase {

@ThreadSafe
public abstract class CloseableHttpClient implements HttpClient, Closeable {

@ThreadSafe
public class PoolingHttpClientConnectionManager
    implements HttpClientConnectionManager, ConnPoolControl<HttpRoute>, Closeable {

@ThreadSafe
public class BasicHttpClientConnectionManager implements HttpClientConnectionManager, Closeable {

These annotations lived in the org.apache.http.annotation package, and their Javadoc said they originated in the book "Java Concurrency in Practice". Because of a licensing issue with the original JCIP library, discussed below, HttpCore 4.4.5 removed these four annotations, and HttpClient has used @Contract since 4.5.3.

JCIP Annotations

Each project can define its own annotations, as HttpClient did. Using annotations from widely adopted open source, however, spares users from learning something new. SpotBugs and IntelliJ IDEA, covered later, include the JCIP package in their default lists of recognized annotations. The JCIP annotations that HttpClient 4.x borrowed are the starting point for such shared annotations.

The JCIP annotations are the thread safety annotations proposed in Appendix A of "Java Concurrency in Practice". There are four:

@ThreadSafe: a thread-safe class
@NotThreadSafe: a class that is not thread-safe
@Immutable: an immutable class. An immutable class is thread-safe.
@GuardedBy("lock"): placed on a field or method to indicate which lock must be held when accessing it. It can name either an intrinsic lock used by synchronized or a java.util.concurrent.locks.Lock.

The first three annotations tell users about the class’s contract, and @GuardedBy tells maintainers of the class which lock to respect.

Effective Java, Second Edition (2008) came out after JCIP (2006) and explains its five levels by comparing them with the JCIP annotations. Lining up the two classifications, the four levels other than thread-hostile map onto the three class-level JCIP annotations. Unconditionally thread-safe and conditionally thread-safe are both covered by @ThreadSafe.

Effective Java level JCIP annotation Difference

Effective Java level	JCIP annotation	Difference
Immutable	`@Immutable`	JCIP considers immutable classes thread-safe, so `@ThreadSafe` is not added on top.
Unconditionally thread-safe	`@ThreadSafe`	Same meaning.
Conditionally thread-safe	`@ThreadSafe`	JCIP has no separate name for this. Which lock to hold goes in the description. This is where the two classifications actually diverge.
Not thread-safe	`@NotThreadSafe`	JCIP treats this annotation as optional.
Thread-hostile	None	JCIP has no corresponding concept.
Not applicable	`@GuardedBy("lock")`	Placed on fields and methods, for maintainers. The five levels of Effective Java are a class-level contract with users, so the basis of classification itself is different.

Immutable

@Immutable

JCIP considers immutable classes thread-safe, so @ThreadSafe is not added on top.

Unconditionally thread-safe

@ThreadSafe

Same meaning.

Conditionally thread-safe

@ThreadSafe

JCIP has no separate name for this. Which lock to hold goes in the description. This is where the two classifications actually diverge.

Not thread-safe

@NotThreadSafe

JCIP treats this annotation as optional.

Thread-hostile

None

JCIP has no corresponding concept.

Not applicable

@GuardedBy("lock")

Placed on fields and methods, for maintainers. The five levels of Effective Java are a class-level contract with users, so the basis of classification itself is different.

In short, Effective Java divides classes into five levels by how much external synchronization users need. JCIP uses a safe-or-not dichotomy with immutability added as a special case, and separates information for maintainers into @GuardedBy. Section 4.5 of JCIP, "Documenting synchronization policies", recommends documenting thread safety guarantees for users and synchronization policies for maintainers.

Annotations Spread Under the JCIP Names

The original library distributed with the JCIP book is net.jcip:jcip-annotations:1.0 on Maven Central. Its license, however, is Creative Commons Attribution, a license that the Creative Commons foundation itself does not recommend for software. That led to com.github.stephenc.jcip:jcip-annotations:1.0-1, a reimplementation of the same API under the Apache License 2.0. The two libraries share the package name (net.jcip.annotations) and the annotation names.

The JCIP annotations have also been copied into several other projects. The following libraries use the same annotation names in different packages.

javax.annotation.concurrent: com.google.code.findbugs:jsr305, the JSR-305 annotation implementation distributed by FindBugs, contains the same four annotations. JSR-305 itself was abandoned without a final release and is dormant. On Java 9 and 10, the javax.annotation package in this jar placed on the module path could conflict with the JDK’s java.xml.ws.annotation module. That JDK module was removed in JDK 11, however, so the problem does not apply to every version since Java 9.
com.google.errorprone.annotations: @Immutable and @ThreadSafe used by Google’s Error Prone, plus @GuardedBy in the concurrent subpackage.
androidx.annotation.GuardedBy: for Android.
org.apache.http.annotation: as seen above, the four annotations Apache HttpComponents copied and used up to 4.5.2. They were replaced by @Contract in HttpCore 4.4.5 and HttpClient 4.5.3.

Choosing Annotations for Your Purpose

The original JCIP library is hard to recommend for new projects because of its license, and JSR-305 because its standardization was abandoned. Instead, considering the coverage of the static analysis tools in the next section, I recommend one of the following two libraries.

If compile-time verification comes first, error_prone_annotations is the right fit. With Error Prone, @Immutable and @GuardedBy can be checked at compile time. Guava declares this library as a compile-scope dependency (as of 33.7.1-jre), so projects that use Guava get it on the compile classpath as a transitive dependency. If you use it directly in code, though, it is safer to declare the dependency explicitly rather than rely on the transitive one. Error Prone does not check @ThreadSafe, and the library has no @NotThreadSafe. You therefore also need a convention that unmarked classes are considered not thread-safe.
If expressing all four JCIP annotations in your public API, including @NotThreadSafe, comes first, com.github.stephenc.jcip:jcip-annotations is the right fit. IntelliJ and SpotBugs include this package (net.jcip.annotations) in their default lists, so a project that uses both tools only needs to add one dependency.

What Static Analysis Tools Check

Annotations are valuable as documentation alone, but they become more useful when tools catch violations. This section describes how far SpotBugs, Error Prone, and IntelliJ IDEA each go. Tool coverage can change between versions, so here are the versions I ran or checked against documentation for this article.

Table 1. Verification baseline
Target	Version and how it was checked
Java	JDK 25
SpotBugs	SpotBugs 4.10.4 with Gradle plugin 6.5.11, run on the examples
Error Prone	Error Prone 2.50.0 with Gradle plugin 5.1.1, run on the examples
IntelliJ IDEA	Inspectopedia 2026.2 documentation and the inspection registrations in IntelliJ Community source 826413b22cfe
SonarQube	Built-in rules of the Java analyzer in SonarJava source 9bf31b6e0037 and its list of SpotBugs external rules
Eclipse JDT	JDT Core Options and Eclipse JDT source 8c40c7d2ae12

In the full list of JDT Core Options as of September 2026 and in Eclipse JDT source 8c40c7d2ae12, I found no compiler check that deals with thread safety annotations. Eclipse users can fill the gap with the SpotBugs Eclipse plugin.

At the same point in time, I searched the built-in rule implementations in SonarJava source 9bf31b6e0037, the Java analyzer for SonarQube, for ThreadSafe, GuardedBy, and javax.annotation.concurrent. S3077 was the only implementation that referred to thread safety annotations. I found no rule that directly verifies contracts declared with annotations. The S3077 implementation, which flags volatile on reference-type fields, makes an exception when the field’s type carries @Immutable or @ThreadSafe from the JSR-305 package. It does not handle @GuardedBy.

SonarQube can import SpotBugs reports as external issues. Its list of external rules includes all three bug patterns covered below. To see these results in SonarQube, then, you run SpotBugs in the build to produce an XML report and pass it with sonar.java.spotbugs.reportPaths.

The SpotBugs and Error Prone examples are in examples/thread-safety-static-analysis.

SpotBugs

SpotBugs, the successor to FindBugs, has one bug pattern for the JCIP annotations, and it is for @Immutable. @GuardedBy and @ThreadSafe have no dedicated checks. Instead, a detector that looks for inconsistently synchronized fields reads them as input to its judgment. SpotBugs recognizes three packages:

net.jcip.annotations (original JCIP)
javax.annotation.concurrent (JSR-305)
jakarta.annotation.concurrent (recognized in advance as part of SpotBugs' support for the jakarta namespace; Jakarta Annotations 3.0.0 has no such package)

The JCIP_FIELD_ISNT_FINAL_IN_IMMUTABLE_CLASS bug pattern, which dates back to FindBugs 2.0, warns when a class annotated with @Immutable has a field that is not final. The SpotBugs 4.10.4 implementation, however, excludes transient and volatile fields from this check.

Create a class declared @Immutable that nevertheless has a setter,

Memo.java

package net.benelog;

import net.jcip.annotations.Immutable;

/**
 * Declared {@code @Immutable} but has a non-final field, so
 * SpotBugs reports JCIP_FIELD_ISNT_FINAL_IN_IMMUTABLE_CLASS.
 */
@Immutable
public class Memo {
	private String content;

	public void setContent(String content) {
		this.content = content;
	}

	public String getContent() {
		return content;
	}
}

configure the SpotBugs plugin in Gradle,

spotbugs/build.gradle.kts

plugins {
	java
	id("com.github.spotbugs") version "6.5.11"
}

repositories {
	mavenCentral()
}

dependencies {
	implementation("com.github.stephenc.jcip:jcip-annotations:1.0-1")
}

java {
	toolchain {
		languageVersion.set(JavaLanguageVersion.of(25))
	}
}

spotbugs {
	toolVersion.set("4.10.4")
	ignoreFailures.set(true)
	if (project.hasProperty("reportLow")) {
		// Report low-priority warnings too. The default reports medium and above only.
		reportLevel.set(com.github.spotbugs.snom.Confidence.LOW)
	}
}

tasks.spotbugsMain {
	val report = layout.buildDirectory.file("reports/spotbugs/main.txt")
	reports.create("text") {
		required.set(true)
		outputLocation.set(report)
	}
	doLast {
		println(report.get().asFile.readText())
	}
}

and run ./gradlew :spotbugs:spotbugsMain. The report contains this line:

M B JCIP: Memo.content should be final since net.benelog.Memo is marked as Immutable.  In Memo.java

The example sets ignoreFailures to true so that the report is printed in full even when there are warnings. To fail the build on violations in real CI, change this setting to false or omit it.

@GuardedBy is handled by the IS_FIELD_NOT_GUARDED bug pattern. This pattern, however, does not find violations by looking at the annotation. The IS2_INCONSISTENT_SYNC detector estimates missing synchronization from the proportion of field accesses made while holding a lock. When a field carries @GuardedBy("this"), the detector treats it differently in three ways:

It renames the bug pattern to IS_FIELD_NOT_GUARDED.
It keeps fields as candidates even if no access holds the lock.
It raises the warning priority.

The only value it recognizes is "this". The detector treats fields where less than half of the accesses hold the lock as likely false positives and lowers their priority.

That is why Counter in the same project is not reported with the default settings, even though it modifies a @GuardedBy("this") field without a lock. The read and write in increment() happen without a lock, and only the read in the synchronized method get() holds it. One of three accesses, or 33%, holds the lock. Only when you make the example report low-priority warnings too with ./gradlew :spotbugs:spotbugsMain -PreportLow does it appear.

L M IS: Counter.count not guarded against concurrent access; locked 33% of time  Unsynchronized access at Counter.java:[line 16]

The class below has the same violation plus two more synchronized methods, which brings the locked accesses to 60%.

LockedCounter.java

package net.benelog;

import net.jcip.annotations.GuardedBy;
import net.jcip.annotations.ThreadSafe;

/**
 * Same violation as Counter, but more synchronized methods raise
 * the proportion of locked accesses. SpotBugs reports IS_FIELD_NOT_GUARDED.
 */
@ThreadSafe
public class LockedCounter {
	@GuardedBy("this")
	private int count;

	public void increment() {
		count++;
	}

	public synchronized int get() {
		return count;
	}

	public synchronized void reset() {
		count = 0;
	}

	public synchronized boolean isZero() {
		return count == 0;
	}
}

This class is reported with high priority even with the default settings. The first letter of the output is the priority and the second is the category.

H M IS: LockedCounter.count not guarded against concurrent access; locked 60% of time  Unsynchronized access at LockedCounter.java:[line 16]

The same detector also reads @ThreadSafe and @NotThreadSafe. It excludes fields of @NotThreadSafe classes from the check and uses @ThreadSafe on a class as grounds for raising the warning priority of its fields. It does not verify that the contract declared by the annotation is kept. A class declared @ThreadSafe can hold a field of a @NotThreadSafe type without a warning.

In short, the only thing SpotBugs checks deterministically from annotations alone is the final rule for @Immutable classes. @GuardedBy violations are also reported as estimates based on the proportion of locked accesses; the annotation only changes the candidates and priority of that estimate.

Error Prone

Google’s Error Prone plugs into javac and checks rules that prevent errors at compile time.

Checking @GuardedBy

Error Prone’s GuardedBy check reports a compile error when a field or method annotated with @GuardedBy(lock) is accessed without holding the specified lock. Unlike SpotBugs, whose reporting depends on access proportions, it decides for each access within its analysis scope whether the lock is held. It does not check accesses inside constructors and initializer blocks, or fields protected by a ReadWriteLock.

The annotations this check recognizes include:

com.google.errorprone.annotations.concurrent.GuardedBy
javax.annotation.concurrent.GuardedBy
androidx.annotation.GuardedBy for Android

The original JCIP net.jcip.annotations.GuardedBy is not on the list. The documentation states that the @Immutable check targets only com.google.errorprone.annotations.Immutable and excludes javax.annotation.concurrent.Immutable. The next section confirms this.

In Gradle, the net.ltgt.errorprone plugin attaches Error Prone to javac. To compare annotations from three packages, the example includes all three libraries.

errorprone/build.gradle.kts

plugins {
	java
	id("net.ltgt.errorprone") version "5.1.1"
}

repositories {
	mavenCentral()
}

dependencies {
	implementation("com.github.stephenc.jcip:jcip-annotations:1.0-1")
	implementation("com.google.code.findbugs:jsr305:3.0.2")
	implementation("com.google.errorprone:error_prone_annotations:2.50.0")
	errorprone("com.google.errorprone:error_prone_core:2.50.0")
}

java {
	toolchain {
		languageVersion.set(JavaLanguageVersion.of(25))
	}
}

Compiling the following class, which uses the JSR-305 @GuardedBy,

JsrCounter.java

package net.benelog;

import javax.annotation.concurrent.GuardedBy;
import javax.annotation.concurrent.ThreadSafe;

/**
 * JSR-305 package. Error Prone reports the @GuardedBy violation as a compile error.
 */
@ThreadSafe
public class JsrCounter {
	@GuardedBy("this")
	private int count;

	public void increment() {
		count++;
	}

	public synchronized int get() {
		return count;
	}
}

makes Error Prone 2.50.0 report this error:

JsrCounter.java:15: error: [GuardedBy] This access should be guarded by 'this', which is not currently held
		count++;
		^
    (see https://errorprone.info/bugpattern/GuardedBy)

JcipCounter, the same code with only the import changed to net.jcip.annotations.GuardedBy, compiles without any error. Conversely, ErrorProneCounter, which uses @GuardedBy from Error Prone’s own package, is caught with the same error as JsrCounter. The three classes are in the errorprone subproject of the example repository, and you can check them with ./gradlew :errorprone:compileJava.

Checking @Immutable

The Immutable check verifies that a class annotated with com.google.errorprone.annotations.Immutable is deeply immutable. The SpotBugs JCIP check only looks at whether fields are final, while Error Prone also checks whether the types of reference fields are immutable. The conservative definition of immutability in the Error Prone documentation also requires that this not escape from the constructor. The ImmutableChecker in 2.50.0, however, does not analyze this escaping from ordinary constructor bodies. The class below has one field that is not final and one field that is final but of a mutable type.

ErrorProneMemo.java

package net.benelog;

import java.util.List;

import com.google.errorprone.annotations.Immutable;

/**
 * Error Prone's own @Immutable. Both the non-final field and
 * the final field of a mutable type are reported as compile errors.
 */
@Immutable
public class ErrorProneMemo {
	private String content;
	private final List<String> tags;

	public ErrorProneMemo(String content, List<String> tags) {
		this.content = content;
		this.tags = tags;
	}

	public String getContent() {
		return content;
	}

	public List<String> getTags() {
		return tags;
	}
}

Both fields are reported as compile errors.

ErrorProneMemo.java:13: error: [Immutable] type annotated with @Immutable could not be proven immutable: 'ErrorProneMemo' has non-final field 'content'
	private String content;
	               ^
    (see https://errorprone.info/bugpattern/Immutable)
  Did you mean 'private final String content;'?
ErrorProneMemo.java:14: error: [Immutable] type annotated with @Immutable could not be proven immutable: 'ErrorProneMemo' has field 'tags' of type 'java.util.List<java.lang.String>', 'List' is mutable
	private final List<String> tags;
	                           ^
    (see https://errorprone.info/bugpattern/Immutable)

For tags to pass, its type must be one that Error Prone knows to be immutable or one annotated with @Immutable. A class that implements an interface annotated with @Immutable is subject to the same check. For generic classes, the containerOf attribute specifies which type parameters must be immutable.

JsrMemo, the same code with only the import changed to javax.annotation.concurrent.Immutable, compiles without errors. @GuardedBy is checked for the JSR-305 package too, but @Immutable is checked only for Error Prone’s own package.

Checking @ThreadSafe

com.google.errorprone.annotations.ThreadSafe also has a ThreadSafe check page. It sits in the "Experimental" group of the bug pattern list, so it looks as if you only need to turn it on, but in fact you cannot. Enabling it in the Gradle plugin with options.errorprone.error("ThreadSafe") fails the build with the error "ThreadSafe is not a valid checker name". BuiltInCheckerSuppliers, the list of built-in checks in the Error Prone 2.50.0 source, contains GuardedByChecker and ImmutableChecker but not ThreadSafeChecker. It was also missing from the earlier versions I checked, 2.3.0 through 2.45.0. The checker class itself is included in the error_prone_core jar.

So the class below compiles without any error under the default settings.

ErrorProneRegistry.java

package net.benelog;

import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

import com.google.errorprone.annotations.ThreadSafe;

/**
 * Error Prone's own @ThreadSafe. Error Prone 2.50.0 does not check it by default.
 * Registering ThreadSafeChecker with -PthreadSafeCheck reports fields modified without a lock
 * and final fields of non-thread-safe types as compile errors.
 */
@ThreadSafe
public class ErrorProneRegistry {
	private int count;
	private final Map<String, String> entries = new HashMap<>();
	private final ConcurrentHashMap<String, String> safeEntries = new ConcurrentHashMap<>();

	public void register(String key, String value) {
		count++;
		entries.put(key, value);
		safeEntries.put(key, value);
	}

	public int getCount() {
		return count;
	}
}

To see what this checker looks at, I created the threadsafe-check subproject in the example repository. It is experimental code that registers a subclass of ThreadSafeChecker in META-INF/services so that Error Prone loads it as a plugin check. Error Prone uses ServiceLoader to find checks on the compiler’s annotation processor path, with com.google.errorprone.bugpatterns.BugChecker as the service interface. So all you need is a file with that name that lists the checker class name.

META-INF/services/com.google.errorprone.bugpatterns.BugChecker

com.google.errorprone.bugpatterns.threadsafety.ThreadSafeCheck

The registered class is a wrapper that extends ThreadSafeChecker and names the check with @BugPattern. Because the constructor of ThreadSafeChecker is package-private, the wrapper uses the same package name. It also has a nominal public no-argument constructor, which ServiceLoader requires. Since this code depends on the internals of 2.50.0, I do not recommend it for real projects.

ThreadSafeCheck.java

package com.google.errorprone.bugpatterns.threadsafety;

@BugPattern(
		name = "ThreadSafe",
		summary = "Type declaration annotated with @ThreadSafe is not thread safe",
		severity = ERROR)
public class ThreadSafeCheck extends ThreadSafeChecker {

	/** Public no-argument constructor required by ServiceLoader. Error Prone uses the @Inject constructor. */
	public ThreadSafeCheck() {
		super(null, null);
	}

	@Inject
	ThreadSafeCheck(WellKnownThreadSafety wellKnownThreadSafety,
			ThreadSafeAnalysis.Factory threadSafeAnalysisFactory) {
		super(wellKnownThreadSafety, threadSafeAnalysisFactory);
	}
}

Adding this subproject as a dependency in the errorprone configuration of the project under analysis registers it as a plugin check. The example adds it only when a Gradle property is present; this part was omitted from the build.gradle.kts quoted earlier.

errorprone/build.gradle.kts

dependencies {
	errorprone("com.google.errorprone:error_prone_core:2.50.0")
	if (project.hasProperty("threadSafeCheck")) {
		// Register ThreadSafeChecker, which is not in the default check list, as a plugin.
		errorprone(project(":threadsafe-check"))
	}
}

Running ./gradlew :errorprone:compileJava -PthreadSafeCheck reports the following:

ErrorProneRegistry.java:16: error: [ThreadSafe] @ThreadSafe class fields should be final or annotated with @GuardedBy. See https://errorprone.info/bugpattern/ThreadSafe for details.
	private int count;
	            ^
    (see https://errorprone.info/bugpattern/ThreadSafe)
  Did you mean 'private final int count;'?
ErrorProneRegistry.java:17: error: [ThreadSafe] @ThreadSafe class has non-thread-safe field, 'Map' is not thread-safe
	private final Map<String, String> entries = new HashMap<>();
	                                  ^
    (see https://errorprone.info/bugpattern/ThreadSafe)

To pass this check, every instance field must be one of the following:

final, with a declared type that Error Prone knows to be thread-safe
annotated with @GuardedBy

static fields are not checked, and @LazyInit fields are exempt from the final requirement. count is caught because it is neither final nor @GuardedBy. entries is caught because its declared type Map is not a thread-safe type. Even if the actual object is a ConcurrentHashMap, a field declared as Map is caught. safeEntries, whose declared type is also ConcurrentHashMap, passes. ErrorProneCounter, shown earlier, passes this check because count has @GuardedBy("this"), and is caught only by the @GuardedBy check.

In short, as of September 2026, Error Prone checks @Immutable and @GuardedBy, but @ThreadSafe serves only as documentation unless you register the checker yourself as a plugin, as shown above.

IntelliJ IDEA

IntelliJ IDEA 2026.2 has six inspections in the Concurrency annotation issues group. Five are for @GuardedBy and one is for @Immutable. No inspection verifies contracts declared with @ThreadSafe.

The Unguarded field access or method call inspection recognizes @GuardedBy from all of these packages:

net.jcip.annotations
javax.annotation.concurrent
org.apache.http.annotation
com.android.annotations.concurrency
androidx.annotation
com.google.errorprone.annotations.concurrent

SpotBugs also reads the original JCIP package, but it handles only @GuardedBy("this") and stops at warnings guessed from access proportions. IntelliJ, by comparison, directly checks the guard expressions of the original JCIP annotation.

The Non-final field in @Immutable class inspection warns when an @Immutable class has a field that is not final. It does not check whether field types are mutable, so its depth is closer to SpotBugs than to Error Prone. Unlike SpotBugs, though, it also warns about transient and volatile fields. The markers this inspection recognizes are:

@Immutable in the original JCIP and JSR-305 packages
Error Prone’s com.google.errorprone.annotations.Immutable
AutoValue’s @AutoValue
The Javadoc @Immutable tag

@ThreadSafe is read only as a hint by the Access to static field locked on instance inspection in the "Threading issues" group. This inspection warns when code holding an instance lock accesses a non-constant static field. If the accessed field is final, it checks the annotations on the field’s declared type and skips the warning if a registered thread safety annotation is present. It therefore does not verify the contract of the annotated class itself. The default list contains these annotations:

@ThreadSafe in the original JCIP, JSR-305, org.apache.http.annotation, and com.android.annotations.concurrency packages
@AnyThread in the androidx.annotation and android.support.annotation packages

Error Prone’s @ThreadSafe is not in the default list.

However, the inspection registrations in IntelliJ IDEA 2026.2 declare every inspection in the "Concurrency annotation issues" group with enabledByDefault="false" and level="WARNING". You have to turn them on yourself under Settings | Editor | Inspections | Java | Concurrency annotation issues. Even when enabled, they are editor warnings and cannot block javac compilation the way Error Prone does. Enforcing them in CI requires a separate runner such as Qodana. Qodana is a code quality platform from JetBrains that runs the same inspections as IntelliJ IDEA in CI, as a Docker image or a command-line tool. You enable the checks in a Qodana profile and set a failure condition.

Across the three tools, the range checked deterministically from annotations alone is narrow.

SpotBugs directly checks only the final rule for @Immutable classes. It guesses @GuardedBy violations from the proportion of locked accesses, and reads @ThreadSafe and @NotThreadSafe only as input to that guess.
Error Prone catches missing locks for @GuardedBy and deep immutability for @Immutable as compile errors. It does not recognize the original JCIP package, however, and the @ThreadSafe check works only if you register it separately.
IntelliJ IDEA directly checks @GuardedBy from many packages, including the original JCIP, and checks @Immutable at about the same depth as SpotBugs. Its inspections are off by default, though, and are not tied to javac compilation. Enforcing them requires a separate runner such as Qodana or a command-line inspection.

This is why I recommended either error_prone_annotations or jcip-annotations earlier. If you need checks that block compilation, use annotations that Error Prone recognizes. If you want to mark all four annotations and still get checks from your IDE and SpotBugs, use the net.jcip.annotations package (the Apache-licensed reimplementation).

Project-Specific Rules Verified with ArchUnit

The static analysis tools above partially check whether a class carrying an annotation is implemented as declared. Application code, however, has another kind of accident: an object shared by multiple threads holds, as a field and without synchronization, a class marked as not thread-safe.

For example, Spring @RestController and @Service beans are singletons unless a separate scope is specified, so all request threads share their fields. You could use another scope such as request scope. Some projects, however, prevent the problem by making it a policy that controllers must not hold such types as fields at all. Rules like this depend on the structure each project aims for, so general-purpose static analysis tools do not have them. With ArchUnit, you can write such a rule as a JUnit test and check it on every build.

Example Code

The example has a class annotated with @NotThreadSafe and a controller that holds it as a field. The controller also has a SimpleDateFormat field. The full project is in examples/thread-safety-archunit.

ReportFormatter.java

package net.benelog.report;

import net.jcip.annotations.NotThreadSafe;

@NotThreadSafe
public class ReportFormatter {
	private final StringBuilder buffer = new StringBuilder();

	public String format(String title, String body) {
		buffer.setLength(0);
		return buffer.append(title).append('\n').append(body).toString();
	}
}

ReportController.java

package net.benelog.web;

import java.text.SimpleDateFormat;
import java.util.Date;

import net.benelog.report.ReportFormatter;
import net.benelog.report.ReportService;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ReportController {
	private final ReportService reportService;
	private final ReportFormatter formatter = new ReportFormatter();
	private final SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");

	public ReportController(ReportService reportService) {
		this.reportService = reportService;
	}

	@GetMapping("/reports/{id}")
	public String report(@PathVariable long id) {
		return formatter.format(dateFormat.format(new Date()), reportService.find(id));
	}
}

Rules and Results

The ArchUnit test consists of two rules.

The first rule fails if the type of any field in a class annotated with @RestController carries @NotThreadSafe, without separately analyzing external synchronization or bean scope. ArchUnit reads annotations from bytecode. It can therefore check annotations with RUNTIME retention, such as the original JCIP annotations, as well as those with CLASS retention, such as the JSR-305 annotations and HttpClient’s @Contract. The example rule looks only at net.jcip.annotations.NotThreadSafe, though, so checking annotations from other packages or the threading value of @Contract requires additional conditions. Library classes outside the analyzed packages are also read from the classpath under the default settings, so the same rule can check @NotThreadSafe that a library has applied.

The second rule is for JDK classes that carry no thread safety annotation, such as SimpleDateFormat. It lists Format, Calendar, and StringBuilder explicitly.

ThreadSafetyArchTest.java

package net.benelog;

import static com.tngtech.archunit.core.domain.JavaClass.Predicates.assignableTo;
import static com.tngtech.archunit.core.domain.properties.CanBeAnnotated.Predicates.annotatedWith;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.fields;

import java.text.Format;
import java.util.Calendar;

import com.tngtech.archunit.base.DescribedPredicate;
import com.tngtech.archunit.core.domain.JavaClass;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;
import net.jcip.annotations.NotThreadSafe;
import org.springframework.web.bind.annotation.RestController;

@AnalyzeClasses(packages = "net.benelog")
class ThreadSafetyArchTest {

	@ArchTest
	static final ArchRule controllers_should_not_hold_not_thread_safe_types =
			fields().that().areDeclaredInClassesThat().areAnnotatedWith(RestController.class)
					.should().notHaveRawType(annotatedWith(NotThreadSafe.class))
					.because("controllers are singletons by default, so all request threads share their fields");

	private static final DescribedPredicate<JavaClass> KNOWN_NOT_THREAD_SAFE_JDK_TYPES =
			assignableTo(Format.class)
					.or(assignableTo(Calendar.class))
					.or(assignableTo(StringBuilder.class))
					.as("JDK types that are not thread-safe (Format, Calendar, StringBuilder)");

	@ArchTest
	static final ArchRule controllers_should_not_hold_known_not_thread_safe_jdk_types =
			fields().that().areDeclaredInClassesThat().areAnnotatedWith(RestController.class)
					.should().notHaveRawType(KNOWN_NOT_THREAD_SAFE_JDK_TYPES)
					.because("JDK classes carry no thread safety annotations, so a list blocks them");
}

Running ./gradlew test with ArchUnit 1.5.0, Spring Web 7.0.9, JUnit 6.1.3, and JDK 25 fails both rules and reports which field broke each rule.

Architecture Violation [Priority: MEDIUM] - Rule 'fields that are declared in classes that are annotated with @RestController should not have raw type annotated with @NotThreadSafe, because controllers are singletons by default, so all request threads share their fields' was violated (1 times):
Field <net.benelog.web.ReportController.formatter> has raw type annotated with @NotThreadSafe in (ReportController.java:0)

Architecture Violation [Priority: MEDIUM] - Rule 'fields that are declared in classes that are annotated with @RestController should not have raw type JDK types that are not thread-safe (Format, Calendar, StringBuilder), because JDK classes carry no thread safety annotations, so a list blocks them' was violated (1 times):
Field <net.benelog.web.ReportController.dateFormat> has raw type JDK types that are not thread-safe (Format, Calendar, StringBuilder) in (ReportController.java:0)

HealthController in the same project, which holds only Clock and DateTimeFormatter as fields, passed both rules.

ReportController, caught by the rules, can be fixed by holding the immutable DateTimeFormatter as a field instead of SimpleDateFormat, and by confining ReportFormatter to a local variable of the request-handling method.

ReportController after the fix

private static final DateTimeFormatter DATE_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd");

@GetMapping("/reports/{id}")
public String report(@PathVariable long id) {
	ReportFormatter formatter = new ReportFormatter();
	return formatter.format(DATE_FORMAT.format(LocalDate.now()), reportService.find(id));
}

After changing ReportController this way and running the test again, both rules pass. ReportFormatter is created anew on each call and is not shared with other request threads. Passing the rules, however, does not prove the thread safety of the whole controller. Other shared state and race conditions in sequences of method calls need separate review.

This approach also has limits.

In this rule, ArchUnit looks only at the raw declared type of a field. It cannot catch an ArrayList assigned to a field declared as List, or a non-thread-safe type used as a generic type argument.
It also misses cases where only a supertype carries the annotation and the actual declared type does not, unless you traverse the hierarchy separately.
The rule does not judge whether field access is protected by an external lock or whether the controller has a separate scope.
JDK types without annotations require a manually maintained list, as in the second rule.
The rule looks only at fields declared directly in classes annotated with @RestController. It therefore also misses fields inherited from an unannotated superclass.

Summary

When a Java class is used by multiple threads in a way it was not designed for, the side effects are serious and the source of the problem is hard to trace. That is why thread safety must be documented clearly. Writing it in Javadoc prose, however, leaves its place and wording different in every class, and it works only if people read carefully.

Marking thread safety with annotations gives it a consistent place and format and makes it readable by tools. I recommend Error Prone’s annotations or the Apache-licensed reimplementation of the JCIP annotations. Error Prone blocks @GuardedBy and @Immutable violations with compile errors, IntelliJ IDEA reports some violations as editor warnings, and SpotBugs reports some in its analysis reports. None of the three tools, however, verifies contracts declared with @ThreadSafe under default settings.

For thread safety rules specific to your project, I recommend checking them with ArchUnit.

References

Books
- Effective Java, Third Edition: Item 82. Document thread safety
- Java Concurrency in Practice: 4.5 Documenting synchronization policies, Appendix A. Annotations for Concurrency
Annotation libraries
Javadoc examples
Static analysis tools
Spring Framework Bean Scopes
ArchUnit User Guide

MySQL JDBC Configuration for High-Performance Batch Jobs

Sat, 3 Oct 2026 00:00:00 +0000

Table of Contents

Using Server-Side Prepared Statements
Improving Batch Update Performance
Options for Large-Scale Data Retrieval
- Streaming Results One Row at a Time
- Using Server-side Cursors
References

Batch jobs stress a JDBC driver differently from a web application. They run the same statement many times, insert or update rows in bulk, and read result sets that do not fit in memory. MySQL Connector/J has several connection options that change how it behaves in each of those situations, and most of them are off by default. This article walks through the options that matter most for batch work, what each one actually does on the wire, and the pitfalls to watch for when combining them.

Using Server-Side Prepared Statements

PreparedStatement helps optimize repeated query execution. Instead of declaring the entire SQL string such as SELECT * FROM CITY WHERE COUNTRY = 'KOREA' AND POPULATION > 10000, it separates the static SQL structure SELECT * FROM CITY WHERE COUNTRY = ? AND POPULATION > ? from the dynamic parameters.

When a query is executed repeatedly, the server reuses the parse tree built by parsing the SQL and executes it with different parameters. This reduces CPU and other resource usage on the server. If the JDBC driver sends only the varying parameters instead of transmitting the entire query for each execution, the amount of network traffic can also be reduced. Whether such optimizations actually occur depends on the DBMS and configuration options.

MySQL provides the useServerPrepStmts option to control whether PreparedStatement optimization is performed on the server side.

Since the default value is false, the JDBC driver sends the fully substituted SQL string to the server for every execution when no additional configuration is applied. This is referred to as client-side PreparedStatement or emulated PreparedStatement. This default behavior has the advantage of requiring only one network round-trip per query, but server-side optimizations are not applied.

In environments such as typical web applications, where a variety of queries are executed, it may be more efficient to keep the default behavior while enabling cachePrepStmts=true and increasing related cache sizes. ^[1]

Setting useServerPrepStmts=true enables PreparedStatement parsing on the server side. When a PreparedStatement object is created, the template query containing ? placeholders is first sent to the server, parsed, and prepared. Each time execute() is called, only the parameter values are transmitted, and the already-prepared query is executed. If the same query is executed repeatedly, the parse tree built from SQL parsing is reused, improving performance and reducing network bandwidth. However, MySQL clears the optimization state once execution finishes and optimizes again on the next execution, so you cannot assume the execution plan is built only once and reused indefinitely. ^[2] On the other hand, since at least two network round-trips (prepare, execute) are required to execute a query, performance may actually degrade for queries that are executed only once.

If your application repeatedly executes the same query in MySQL, the useServerPrepStmts=true option is worth trying out. However, MySQL parses quickly and rebuilds the execution plan on every execution, so the gain from this option may be small. In the two performance tests introduced in the footnote above, server-side prepared statements were not faster than client-side ones. When enabling this option, also enable cachePrepStmts=true so that the prepare request does not add a network round-trip on every execution, and measure performance with your actual batch job to decide whether to keep it.

In MySQL versions prior to 5.1.17, using this option prevented queries from using the query cache, but from 5.1.17 onwards it can be used together with the query cache. Note that the query cache itself was deprecated in MySQL 5.7.20 and removed in 8.0, so this constraint no longer matters on 8.0 and later. ^[3] In MariaDB 10.6 and later, additional optimizations reduce metadata retransmission when using useServerPrepStmts=true, resulting in even better performance. ^[4]

Improving Batch Update Performance

When inserting or updating multiple rows, using the JDBC Statement.executeBatch() method can execute them faster than repeatedly calling executeUpdate() for single statements. MySQL can further optimize batch update performance by enabling the rewriteBatchedStatements=true option in the JDBC connection URL.

Since the default value is false, it must be explicitly enabled. When enabled, the MySQL JDBC driver combines multiple individual queries into a single statement. For example, let’s look at inserting three rows with a batch update using the following INSERT query:

Single INSERT form

INSERT INTO access_log(access_date_time, ip, username) VALUES (?, ?, ?);

Without rewriteBatchedStatements=true, the driver executes the above statement three times. With the option enabled, the driver merges them into a single statement:

Merged INSERT form

INSERT INTO access_log(access_date_time, ip, username) VALUES
  (?, ?, ?),
  (?, ?, ?),
  (?, ?, ?);

Since the server processes the merged INSERT as a single statement, one execution of that statement takes longer. In replicated environments, this can increase the burden of replication lag.

Even when multi-value VALUES clauses are not possible, the driver still combines multiple INSERT or UPDATE statements separated by ; into a single transmission when the batch contains four or more statements. Batches of three or fewer statements are executed one by one. The direct benefit of this mode is packing multiple SQL statements into one request to reduce network round-trips. Unlike the multi-value INSERT, which the server processes as a single statement, the ;-combined form merely transmits several statements at once, so the parsing and execution of each statement are not merged into one.

Be aware that rewriteBatchedStatements=true may conflict with other JDBC options or require additional tuning. The Connector/J documentation once stated that rewriteBatchedStatements was ignored when used together with useServerPrepStmts=true, or with useCursorFetch=true (introduced later in this document) which implicitly enables it. The 8.0.30 release notes corrected this as a documentation error. ^[5] Query rewriting now applies as-is even when combined with server-side PreparedStatements.

When combining queries, the driver calculates on its own how many statements to merge at once so that the combined statement stays within the max_allowed_packet limit. Therefore a small value usually does not cause an error; it just reduces how many statements are merged at once, shrinking the benefit of combining queries. To insert or update large volumes at once, it is better to set this value generously.

max_allowed_packet can be set in the MySQL configuration file or as a global system variable. The session value is read-only and initialized from the global value when the connection is established, so if you change the global value dynamically, new connections use the changed value. ^[6] You can check it with: SHOW VARIABLES LIKE 'max%'; Note that the bulk_insert_buffer_size setting is only referenced by the MyISAM engine—which is rarely used today—and can be ignored when using InnoDB.

Due to such conflicts and interactions among options, it may be difficult to find a single DB configuration optimized for both reads and writes. Another possible approach is to declare separate data sources in the application for large-scale read and write operations.

In Connector/J versions up to 8.0.28, inserting BLOB (Binary Large Object) values with a batch update could cause a NullPointerException, but this has been fixed in newer versions. ^[7]

Options for Large-Scale Data Retrieval

If an application using Spring Batch with MySQL executes queries through JdbcCursorItemReader with default settings, the entire result set will be fetched at once and loaded into the application’s memory. When querying large datasets, this can cause Out Of Memory (OOM) errors. To avoid this, you must use ResultSet streaming or server-side cursors.

Streaming Results One Row at a Time

ResultSet streaming retrieves query results gradually instead of receiving them all at once.

To use this approach, configure the PreparedStatement as follows:

Creating PreparedStatement for streaming

PreparedStatement statement = con.prepareStatement(
    sql,
    ResultSet.TYPE_FORWARD_ONLY,
    ResultSet.CONCUR_READ_ONLY
);

statement.setFetchSize(Integer.MIN_VALUE);

Note that calling setFetchSize(Integer.MIN_VALUE) is not technically valid per JDBC specification. The Javadoc for the java.sql.Statement interface states that if a value less than 0 is passed to the setFetchSize(int) method, it should throw a SQLException. However, since MySQL Connector/J enables streaming mode by passing Integer.MIN_VALUE to this method, developers have no choice but to use it that way.

While the streaming mode reduces memory usage, it is not always advantageous. The query request is sent only once and the server pushes the entire result back as consecutive packets, so it does not incur one network round-trip per row. ^[8] Instead, while the driver reads and processes the result one row at a time, server resources and locks are held until the query completes, so the slower the application consumes the rows, the longer this burden lasts. Other drawbacks are that you cannot directly control the size of each transfer, and no other queries can be executed on the same connection until the ResultSet is closed. ^[9]

In Spring Batch, calling JdbcCursorItemReader.setFetchSize(Integer.MIN_VALUE) enables the streaming mode. Statement creation options such as ResultSet.TYPE_FORWARD_ONLY are applied internally within JdbcCursorItemReader. If the JdbcCursorItemReader.verifyCursorPosition property remains at its default true, it conflicts with TYPE_FORWARD_ONLY and produces the following error:

Error caused by verifyCursorPosition=true

org.springframework.dao.TransientDataAccessResourceException: Attempt to process next row failed; SQL [SELECT * FROM access_log]; Operation not allowed for a result set of type ResultSet.TYPE_FORWARD_ONLY.

Accordingly, a JdbcCursorItemReader configured for per-row streaming should be created as follows:

JdbcCursorItemReader for streaming queries in MySQL

return new JdbcCursorItemReaderBuilder<T>()
  .name("streamingDbReader")
  .dataSource(this.dataSource)
  .sql(sql)
  .rowMapper(rowMapper)
  .fetchSize(Integer.MIN_VALUE)
  .verifyCursorPosition(false)
  .build();

Using Server-side Cursors

MySQL server-side cursors work by storing results in a temporary table and allowing the client to fetch the data in configurable chunks. Supported in server versions newer than MySQL 5.0.2, they can be enabled by adding useCursorFetch=true to the JDBC URL. ^[10] Since the default value is false, this option must be explicitly enabled if client-side cursors are not desired.

Even with useCursorFetch=true, server-side cursors will not be used unless a positive fetch size is specified. This can be configured per query using the Statement.setFetchSize(int) method in the JDBC API, or a default value can be set via the defaultFetchSize property in the JDBC connection URL. ^[11]

In Spring Batch, the fetch size can be specified using JdbcCursorItemReader.setFetchSize(int). It is recommended to set this value equal to chunk size in your step configuration.

As mentioned earlier, enabling the useCursorFetch=true option also automatically enables useServerPrepStmts=true.

References

1. For performance test cases combining useServerPrepStmts and cachePrepStmts, see the following articles: https://vladmihalcea.com/mysql-jdbc-statement-caching/ , https://tech.kakaopay.com/post/how-preparedstatement-works-in-our-apps/

2. The MySQL 8.4 manual describes what is cached for prepared statements as an internal structure converted from the SQL; for example, SELECT * is stored expanded into the actual column list. https://dev.mysql.com/doc/refman/8.4/en/statement-caching.html Query_expression.clear_execution() in the MySQL 8.4 source also resets the optimized state to false before a prepared statement is re-executed. https://dev.mysql.com/doc/dev/mysql-server/8.4.9/sql__lex_8h_source.html

3. The deprecation and removal of the query cache is documented in the 'How the Query Cache Operates' section of the MySQL 5.7 Reference Manual: https://dev.mysql.com/doc/refman/5.7/en/query-cache-operation.html

4. This improvement is tracked in https://jira.mariadb.org/browse/MDEV-19237

5. The correction can be found in the following release notes: https://dev.mysql.com/doc/relnotes/connector-j/en/news-8-0-30.html

6. The max_allowed_packet entry in the MySQL 8.4 Reference Manual states that the global value can be changed dynamically but the session value is read-only. https://dev.mysql.com/doc/refman/8.4/en/server-system-variables.html#sysvar_max_allowed_packet

7. See release notes: https://dev.mysql.com/doc/relnotes/connector-j/en/news-8-0-29.html

8. The response structure, in which the server answers a single query request with one packet per row sent in sequence, is described in the following MySQL protocol documentation: https://dev.mysql.com/doc/dev/mysql-server/latest/page_protocol_com_query_response_text_resultset.html

9. This is explained in the ResultSet section of the following Connector/J implementation notes. It describes the restriction that you must read all of the rows (or close the ResultSet) before issuing any other queries on the same connection, and introduces the useCursorFetch option as an alternative that fetches a set number of rows at a time. https://dev.mysql.com/doc/connector-j/en/connector-j-reference-implementation-notes.html

10. The Connector/J documentation used to describe this property as determining whether cursor-based fetching should be used when the server version is newer than MySQL 5.0.2 and the fetch size is greater than 0. As the minimum supported server versions moved up, this version condition was dropped from recent documentation: https://dev.mysql.com/doc/connector-j/en/connector-j-connp-props-performance-extensions.html

11. See: https://dev.mysql.com/doc/connector-j/en/connector-j-connp-props-performance-extensions.html

Running External Processes from Java: JDK 25 on Linux 6.x

Sat, 3 Oct 2026 00:00:00 +0000

This article, based on JDK 25 and Linux 6.x, covers what to watch for when writing Java code that launches external processes, and the libraries you can use for it. It then looks at how the JVM creates child processes on Linux: the posix_spawn() function, the behavior of jspawnhelper, a small executable shipped with the JDK, the launch latency that appears with large heaps, and the setting that changes the launch mechanism. The results in this article were verified in the environment below. The example code is in the GitHub repository.

Item	Value
OS	Ubuntu 24.04.4 LTS, kernel 6.17
Architecture	x86-64
glibc	2.39
JDK	Temurin 25+36
zt-exec	1.13.0
Apache Commons Exec	1.6.0

Item

Value

Ubuntu 24.04.4 LTS, kernel 6.17

Architecture

x86-64

glibc

2.39

JDK

Temurin 25+36

zt-exec

1.13.0

Apache Commons Exec

1.6.0

Pitfalls of Launching External Processes with the JDK Classes

`ProcessBuilder` vs. `Runtime.exec`

An external process launched from Java code is handled through a java.lang.Process object. You get a Process object from ProcessBuilder.start() or Runtime.exec(). ProcessBuilder was added in JDK 5.0 (Java 1.5), and from that release the Sun JDK’s Runtime.exec() was also changed to delegate internally to ProcessBuilder. A contemporary write-up that examined the JDK 1.5.0-beta2 source shows this implementation as well. The Runtime source in OpenJDK 25 likewise creates a ProcessBuilder and calls start(). The two APIs therefore share the process creation implementation; the main difference is how they handle the launch configuration.

I recommend ProcessBuilder for new code. It offers a more convenient API for specifying environment variables, the working directory, and output redirection. The output pipe handling discussed in this article can also be configured with redirectOutput(), redirectError(), redirectErrorStream(), and similar methods.

Item Runtime.exec() ProcessBuilder

Item	Runtime.exec()	ProcessBuilder
When it runs	Runs when `exec()` is called	Runs on `start()` after the configuration is set up
Command and arguments	A single string or an array of strings	Varargs or a list with the arguments already separated
Environment variables	Passed as an array of `NAME=value` strings	Modified through the Map returned by `environment()`
Working directory	Passed as an argument to an overload	Set with `directory()`
I/O configuration	No API for redirection or for merging standard error	Provides `redirectOutput()`, `redirectError()`, `redirectErrorStream()`, `inheritIO()`, and more

When it runs

Runs when exec() is called

Runs on start() after the configuration is set up

Command and arguments

A single string or an array of strings

Varargs or a list with the arguments already separated

Environment variables

Passed as an array of NAME=value strings

Modified through the Map returned by environment()

Working directory

Passed as an argument to an overload

Set with directory()

I/O configuration

No API for redirection or for merging standard error

Provides redirectOutput(), redirectError(), redirectErrorStream(), inheritIO(), and more

In particular, the Runtime.exec(String) family, which takes the command as a single string, has been deprecated since JDK 18. The Runtime Javadoc explains that these methods split arguments on whitespace alone, so they can mishandle things like file names that contain spaces. Adding quotes does not group arguments the way a shell would.

// Cannot pass a file name with a space as a single argument
Runtime.getRuntime().exec("cat \"my file.txt\"");

// Both forms pass the file name as a single argument
Runtime.getRuntime().exec(new String[]{"cat", "my file.txt"});
new ProcessBuilder("cat", "my file.txt").start();

Limits of the `ProcessBuilder` Defaults

In Java, you can launch an external process with a few simple lines of code using the ProcessBuilder class, as shown below.

Calling ProcessBuilder with the defaults

Process process = new ProcessBuilder("echo", "hello").start();
int exitCode = process.waitFor();
System.out.println("exit=" + exitCode);

With echo hello, which produces little output and finishes quickly, this code works without problems. But if you run a command that produces a lot of output, waits on standard input, or never finishes, this code can hang.

Handling the stdout and stderr Pipes

If the child process fills the limited capacity of the standard output (stdout) or standard error (stderr) pipe while the parent process is not reading, the child blocks on its next write. To prevent that, you need code that keeps consuming standard output and standard error. You must use one of the following two approaches.

Read the standard output and standard error streams on separate threads.
- If you need to process or refer to the two outputs separately, read each on its own thread.
- If you do not need to tell the two outputs apart, you can merge them into one and read it on a single thread.
If you do not need to read a stream at all, redirect it to a file, to the parent’s output, or to /dev/null.

The earlier 'Calling ProcessBuilder with the defaults' code used neither of these approaches. The following sections reproduce how this code hangs with examples and explain how to fix it.

Deadlock from an Unread Pipe Buffer

Even with ProcessBuilder, the child process’s standard output and standard error are delivered to the parent process through separate pipes by default. If the parent does not read a pipe, the pipe buffer fills up and the child process cannot finish writing.

This problem occurs even if you never call waitFor(). The parent can go on executing the code that follows the child’s launch, but the child may be unable to finish its work because its write() call to the full pipe blocks. If on top of that the parent just waits for the child to exit with waitFor(), the two end up in a deadlock, each waiting for the other. So removing waitFor() does not solve it; you have to read or redirect the output pipes. The Process Javadoc in JDK 25 warns about this blocking and the possibility of deadlock.

From the Javadoc of the Process class

Because some native platforms only provide limited buffer size for standard input and output streams, failure to promptly write the input stream or read the output stream of the process may cause the process to block, or even deadlock.

The pipe(7) manual page tells how large the "limited buffer size" mentioned in the Javadoc is on Linux. Since kernel 2.6.11 the default pipe capacity has been 16 pages, that is, 64KiB with 4KiB pages. However, it can be smaller depending on the per-user pipe memory limit or system settings, and it can be changed with F_SETPIPE_SZ, so you should not assume 64KiB as a fixed limit.

The code below has the seq 1 100000 command print 588,895 bytes and waits 3 seconds without reading them.

DeadlockDemo.java

Process process = new ProcessBuilder("seq", "1", "100000").start();
boolean finished = process.waitFor(3, TimeUnit.SECONDS);
System.out.println("finished within 3s: " + finished + ", alive: " + process.isAlive());
long lines = process.inputReader().lines().count();
int exitCode = process.waitFor();
System.out.println("read " + lines + " lines, exit=" + exitCode + ", alive: " + process.isAlive());

Output of DeadlockDemo.java

finished within 3s: false, alive: true
read 100000 lines, exit=0, alive: false

After the parent process has waited 3 seconds, the child process is still alive. Once the pipe buffer filled up, the write() call in seq blocked and never returned. When the parent read the pipe to the end, the child wrote the rest of its output and finished with exit code 0 (alive: false). Without the timeout, the parent would have kept waiting in waitFor() as well.

The inputReader() method used in the example was added in JDK 17. Before that, you had to wrap getInputStream() in an InputStreamReader and a BufferedReader.

Using inputReader()

// Before JDK 17
BufferedReader reader = new BufferedReader(
        new InputStreamReader(process.getInputStream()));
long lines = reader.lines().count();

// JDK 17 and later
long lines = process.inputReader().lines().count();

The two snippets choose their default encoding differently. inputReader() decodes with the encoding named by the native.encoding system property, while an InputStreamReader created without arguments uses Charset.defaultCharset(). Since JDK 18 the default charset is UTF-8, but if you specify -Dfile.encoding=COMPAT, the default encoding is determined by the operating system, the locale, and so on, as it was before.

inputReader() does not detect the child process’s output encoding automatically. If the child writes in the same encoding as the parent JVM’s native.encoding, this default is appropriate. If the child explicitly writes UTF-8 or runs under a different locale, you must specify the encoding yourself to match its output, for example inputReader(StandardCharsets.UTF_8).

Reading Both Streams Concurrently

If you need to receive and process standard output and standard error separately, you have to drain both pipes at the same time. Reading one pipe to the end and then reading the other is not enough. If the standard error pipe fills first, the child process cannot write any more standard output, and the parent deadlocks waiting for EOF on standard output. In this case the program hangs in the read before it even reaches waitFor().

The code below runs a command that writes 588,895 bytes to standard error and then one line to standard output, and it reads standard output to the end before reading standard error.

SequentialReadDemo.java

Process process = new ProcessBuilder("sh", "-c", "seq 1 100000 >&2; echo done").start();
System.out.println("reading stdout...");
long outLines = process.inputReader().lines().count();
long errLines = process.errorReader().lines().count();
System.out.println("stdout " + outLines + ", stderr " + errLines + ", exit=" + process.waitFor());

When you run this code, nothing follows the first line no matter how long you wait, and ps shows that the child seq process is still alive.

Output of SequentialReadDemo.java

reading stdout...

seq is blocked because the standard error pipe is full, and the parent is waiting for an EOF on standard output that has not yet arrived. The next line, which reads standard error, never executes, so the deadlock is never broken. Giving each stream its own reader thread avoids neglecting one stream while reading the other. The PlainJdkRunner example later in this article takes that approach.

If you do not need to tell the two outputs apart, you can merge standard error into standard output with redirectErrorStream(true). That leaves only one pipe to read, so a single thread can handle it.

MergedReadDemo.java

Process process = new ProcessBuilder("sh", "-c", "seq 1 100000 >&2; echo done")
        .redirectErrorStream(true)
        .start();
long lines = process.inputReader().lines().count();
System.out.println("read " + lines + " lines, exit=" + process.waitFor());

It is the same command, but this time it runs to completion. The 100,001 lines are the 100,000 lines written to standard error plus the single done line on standard output.

Output of MergedReadDemo.java

read 100001 lines, exit=0

Redirecting Output the Java Process Will Not Read

If the parent process does not need to refer to or process the child’s output, the simplest option is not to create a pipe that the Java code has to read. The alternatives to the default Redirect.PIPE are as follows.

Redirect.INHERIT: the child process writes directly to the parent’s standard output and standard error. (Since JDK 7)
- The inheritIO() method hands down all three of the parent process’s streams (standard input, standard output, and standard error) at once. (Since JDK 7)
Redirect.DISCARD: sends the output to /dev/null. (Since JDK 9)
Redirect.to(File): sends the output to a file. (Since JDK 7)

Redirecting the child process’s output

// Send directly to the parent's stdout and stderr
new ProcessBuilder("seq", "1", "100000")
        .redirectOutput(Redirect.INHERIT)
        .redirectError(Redirect.INHERIT)
        .start()
        .waitFor();

// Inherit all three streams at once, including stdin
new ProcessBuilder("seq", "1", "100000")
        .inheritIO()
        .start()
        .waitFor();

// Discard the output to /dev/null
new ProcessBuilder("seq", "1", "100000")
        .redirectOutput(Redirect.DISCARD)
        .redirectError(Redirect.DISCARD)
        .start()
        .waitFor();

// Send to files
new ProcessBuilder("seq", "1", "100000")
        .redirectOutput(Redirect.to(new File("seq-out.log")))
        .redirectError(Redirect.to(new File("seq-err.log")))
        .start()
        .waitFor();

In this environment, all four approaches printed the same 588,895 bytes as the earlier deadlock example and exited normally. Because no child output pipe is created that the parent JVM has to read itself, there is no deadlock from an unread pipe. However, if the output target inherited through INHERIT is itself a pipe, for example if the parent JVM’s standard output is piped to another program, the child’s writes can block or slow down depending on how fast that program reads. When discarding output, specify DISCARD for both standard output and standard error. If you specify only one, the other remains at the default PIPE, and the earlier deadlock can recur. Redirect.to(File) truncates an existing file and overwrites it, so to append on each run use Redirect.appendTo(File).

Closing stdin and EOF

Standard input (stdin), which the Javadoc quoted above warned about alongside the output streams, also defaults to a pipe. As long as the parent JVM keeps the write end of that pipe open, the child process never receives EOF. A command that reads stdin to the end, such as cat run without arguments, keeps waiting even though no more input is coming, and the parent waits in waitFor() for that command to finish. Draining the output pipes does not release this wait.

If you have no input to send, close the write end with process.getOutputStream().close() right after start(), or specify empty input such as redirectInput(new File("/dev/null")). If you do need to send input, close the stream once you have finished writing. zt-exec and Apache Commons Exec, covered later in this article, close the child’s stdin immediately when no input is specified.

The example below runs cat four times, changing only how stdin is handled.

StdinEofDemo.java

Process opened = new ProcessBuilder("cat").start();
System.out.println("stdin left open: finished within 1s=" + opened.waitFor(1, TimeUnit.SECONDS)
        + ", alive=" + opened.isAlive());
opened.destroy();
opened.waitFor();

Process closed = new ProcessBuilder("cat").start();
closed.getOutputStream().close();
System.out.println("stdin closed: finished within 1s=" + closed.waitFor(1, TimeUnit.SECONDS)
        + ", exit=" + closed.exitValue());

Process devNull = new ProcessBuilder("cat")
        .redirectInput(new File("/dev/null"))
        .start();
System.out.println("/dev/null input: finished within 1s=" + devNull.waitFor(1, TimeUnit.SECONDS)
        + ", exit=" + devNull.exitValue());

Process fed = new ProcessBuilder("cat").start();
try (Writer writer = fed.outputWriter()) {
    writer.write("hello\n");
}
String echoed = fed.inputReader().readLine();
System.out.println("closed after writing: echoed=" + echoed + ", exit=" + fed.waitFor());

Here is the output. Only the first run, which left the stream writing to stdin open, failed to finish within one second; the other three received EOF and exited right away.

Output of StdinEofDemo.java

stdin left open: finished within 1s=false, alive=true
stdin closed: finished within 1s=true, exit=0
/dev/null input: finished within 1s=true, exit=0
closed after writing: echoed=hello, exit=0

The first cat was ended with destroy(). Without that cleanup it would stay alive while the remaining examples run. Once the parent JVM exits, however, the write end of the pipe is closed with it, so at that point cat also receives EOF and exits.

The outputWriter() used in the last example was added in JDK 17 together with inputReader(), and it replaces the code that wraps getOutputStream() in an OutputStreamWriter and a BufferedWriter. Called without arguments it uses the charset from the native.encoding system property, and the outputWriter(Charset) method lets you specify one directly.

Using outputWriter()

// Before JDK 17
try (BufferedWriter writer = new BufferedWriter(
        new OutputStreamWriter(process.getOutputStream()))) {
    writer.write("hello\n");
}

// JDK 17 and later
try (BufferedWriter writer = process.outputWriter()) {
    writer.write("hello\n");
}

Timeouts and Termination Policy

Even when you handle all three pipes connected to the child process as described so far, an external command can still hang while waiting on the network or on a lock. That is why a timeout and a termination policy are needed as well. While the command hangs, the thread that called waitFor() blocks until the external command finishes. The waitFor(long, TimeUnit) method, available since JDK 8, merely returns false when the time runs out; it does not terminate the process. At that point you can request graceful termination with destroy() and fall back to destroyForcibly() if the process is still alive after a grace period, or you can kill it right away as the example below does. In the OpenJDK implementation on Linux, destroy() sends SIGTERM and destroyForcibly() sends SIGKILL. A process can catch SIGTERM with a handler and finish up before exiting: deleting temporary files, releasing locks, or cleaning up the child processes it created. SIGKILL terminates the process with no chance to clean up through a handler, so files and descendant processes that were never cleaned up may be left behind. For commands that have something to clean up, it is therefore safer to send SIGTERM first with destroy() and allow a grace period. Note, however, that the process may still be alive briefly after destroyForcibly() returns, so if you need the termination to be complete, confirm it with waitFor(). The example below only runs commands with nothing to clean up, such as sleep, so it kills them right away. It reads the two output streams on JDK 21 virtual threads and puts a one-second limit on waiting for exit.

PlainJdkRunner.java

static void run(String... command) throws IOException, InterruptedException, TimeoutException {
    Process process = new ProcessBuilder(command).start();
    StringBuilder stdout = new StringBuilder();
    StringBuilder stderr = new StringBuilder();
    Thread outPump = Thread.ofVirtual().start(() -> process.inputReader().lines().forEach(l -> stdout.append(l).append('\n')));
    Thread errPump = Thread.ofVirtual().start(() -> process.errorReader().lines().forEach(l -> stderr.append(l).append('\n')));
    if (!process.waitFor(1, TimeUnit.SECONDS)) {
        process.destroyForcibly().waitFor();
        throw new TimeoutException("timed out: " + String.join(" ", command));
    }
    outPump.join();
    errPump.join();
    System.out.println(command[0] + ": exit=" + process.exitValue()
            + ", stdout chars=" + stdout.length() + ", stderr=" + stderr.toString().trim());
}

Here is the result of running four commands, echo hello, seq 1 100000, ls /no-such-dir, and sleep 60, through this method. The 588,895 bytes of output from seq do not cause a hang, the stderr of ls is collected separately, and sleep, which exceeds one second, ends with an exception.

Output of PlainJdkRunner.java

echo: exit=0, stdout chars=6, stderr=
seq: exit=0, stdout chars=588895, stderr=
ls: exit=2, stdout chars=0, stderr=ls: cannot access '/no-such-dir': No such file or directory
timed out: sleep 60

This example targets commands that require no input and create no descendant processes. To use it safely with other commands, you need to take care of the following as well.

For commands that read stdin, add the EOF handling from the previous section.
Propagate exceptions thrown in the reader threads to the calling thread, and clean up the process and streams on interrupt or timeout as well.
The one-second limit in the code above applies only to waitFor(). If you need an overall timeout that also covers start(), the subsequent wait for termination, and join(), implement it separately.
If the output is very large, do not collect all of it in a StringBuilder; process it line by line or with a fixed-size buffer.
For commands whose output encoding differs from the parent JVM’s native.encoding, specify the encoding with inputReader(Charset).

Cleaning Up Descendant Processes

destroy() and destroyForcibly() send a signal only to the child you created directly. If the command you ran created child processes of its own, those descendants can be left behind. When the child exits first, the descendant processes it created are reparented to PID 1 or to the nearest subreaper process and keep running. A subreaper is a process designated with prctl(PR_SET_CHILD_SUBREAPER); it takes over orphaned descendants in place of PID 1. systemd is the program that, on most Linux distributions, runs first as PID 1 at boot and starts and manages the other services, and it also runs a separate instance called systemd --user for each logged-in user. The systemd --user of a desktop session is one example of a subreaper.

Cases Where Descendants Are Left Behind

There are broadly four situations in which descendant processes are left behind.

Commands run through a shell: this is the case when something like sh -c "a | b" or a script such as run.sh is terminated on timeout. The non-interactive shell running the script does not forward the SIGTERM it received to its children, so only the shell exits.
Programs run through a wrapper or launcher: with npm run, npm, which runs on Node.js, executes the script via sh -c, so ending the npm process can leave the command the shell started running. LibreOffice’s soffice goes through oosplash to run soffice.bin, which does the actual work, and if you end oosplash with SIGKILL, soffice.bin is not terminated and stays behind. git also runs ssh or git-remote-https as a child during fetch or clone.
Programs that turn themselves into daemons: the Gradle daemon, the Kotlin compile daemon, adb start-server, and ssh ControlPersist connections are designed to outlive their caller. Such programs may also leave the original session and group with setsid().
Scripts that do not wait for background jobs: if server & is not followed by wait, server keeps running even after the script exits normally. If this descendant keeps the inherited output pipe open, waitFor() returns but the reader of the output never receives EOF.

Let’s reproduce the first case. The code below runs sleep 60 through a shell, calls destroy() after 0.3 seconds, and then prints which of the descendants it looked up before termination are still alive, along with their parent PIDs.

DescendantLeakDemo.java

public static void main(String[] args) throws Exception {
    run("sh", "-c", "sleep 60");
    run("sh", "-c", "sleep 60; echo done");
    run("sh", "-c", "sleep 60 | cat");
    run("bash", "-c", "sleep 60");
}

static void run(String... command) throws Exception {
    Process process = new ProcessBuilder(command).start();
    Thread.sleep(300);
    List<ProcessHandle> descendants = process.descendants().toList();
    process.destroy();
    process.waitFor(1, TimeUnit.SECONDS);
    Thread.sleep(100);

    List<String> left = descendants.stream()
            .filter(ProcessHandle::isAlive)
            .map(p -> name(p) + "(ppid=" + p.parent().map(ProcessHandle::pid).orElse(-1L) + ")")
            .toList();
    System.out.println(String.join(" ", command) + " -> shell alive=" + process.isAlive()
            + ", children=" + descendants.size() + ", left=" + left);
    descendants.forEach(ProcessHandle::destroyForcibly);
}

Output of DescendantLeakDemo.java

sh -c sleep 60 -> shell alive=false, children=1, left=[sleep(ppid=1693)]
sh -c sleep 60; echo done -> shell alive=false, children=1, left=[sleep(ppid=1693)]
sh -c sleep 60 | cat -> shell alive=false, children=2, left=[sleep(ppid=1693), cat(ppid=1693)]
bash -c sleep 60 -> shell alive=false, children=0, left=[]

In all three cases run with sh -c, the shell exited but sleep and cat remained. PID 1693, the parent of the leftover processes, is the systemd --user of this environment. Note that a descendant was left behind even with sh -c "sleep 60", which has only a single command. dash 0.5.12, the /bin/sh on Ubuntu 24.04, ran even the last command received through -c as a child process. bash -c, on the other hand, replaced the shell process with sleep (children=0), so no descendants were left. Because this behavior varies with the kind and version of the shell, it is safer to assume that commands run through a shell leave descendants behind and to have a cleanup method ready.

If the leftover descendant is a command that will finish soon, the problem lasts only as long as that descendant runs. Even so, a task you have already marked as failed on timeout may keep writing files or calling external APIs in the background during that time. The bigger problem is descendants that never finish on their own. The timeout itself means the command did not finish in time, so there is little reason to expect the leftover descendants to finish soon either. Descendants that are not meant to finish, such as servers or daemons, accumulate with each run and consume memory and the process count limit. If they hold on to a port or a file lock, the next run fails with an error like Address already in use.

If a leftover descendant keeps the inherited output pipe open, a read in progress waits for the descendant to close the pipe, which can delay join() as well. The Process implementation in JDK 25 reclaims the output remaining in the pipe and closes the stream when the direct child exits, but whether a wait occurs depends on the ordering between a read already in progress and this exit handling. As in the example above, you can also look up descendants with ProcessHandle.descendants() from JDK 9 and terminate them one by one. But the result is a snapshot, so it cannot reliably clean up processes created between the lookup and the termination, or those reparented after the parent exited. To end the descendants in one go, you have to manage them with OS-level process groups or cgroups.

Terminating by Process Group

For commands whose descendants stay in the same process group, you can run them under setsid to create a new session and group, and then signal the whole group to clean up once the work is done. The JDK API has no facility for creating a process group or signaling one, so this is put together by running the setsid and kill commands.

ProcessGroupKillDemo.java

public static void main(String[] args) throws Exception {
    run("sleep 60 | cat");
    run("(trap '' TERM; sleep 60) & sleep 60");
    run("setsid sleep 60 & sleep 60");
}

static void run(String script) throws Exception {
    Process process = new ProcessBuilder("setsid", "sh", "-c", script).start();
    List<ProcessHandle> descendants = List.of();
    try {
        if (!process.waitFor(1, TimeUnit.SECONDS)) {
            descendants = process.descendants().toList(); // snapshot for checking the result
        }
    } finally {
        killGroup(process.pid()); // the PID of the child, now a group leader via setsid, is the process group ID
        process.waitFor();
    }

    List<String> left = descendants.stream()
            .filter(ProcessHandle::isAlive)
            .map(p -> p.info().commandLine().orElse("?"))
            .toList();
    System.out.println("[" + script + "] pgid=" + process.pid() + ", left=" + left);
    descendants.forEach(ProcessHandle::destroyForcibly);
}

static void killGroup(long pgid) throws Exception {
    signalGroup("TERM", pgid);
    if (!awaitGroupExit(pgid, 5)) {
        signalGroup("KILL", pgid);
        awaitGroupExit(pgid, 5);
    }
}

static boolean awaitGroupExit(long pgid, long seconds) throws Exception {
    long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(seconds);
    while (signalGroup("0", pgid)) {
        if (System.nanoTime() > deadline) {
            return false;
        }
        Thread.sleep(100);
    }
    return true;
}

// an exit code of 0 from kill means at least one process in the group received the signal
static boolean signalGroup(String signal, long pgid) throws Exception {
    Process kill = new ProcessBuilder("kill", "-" + signal, "--", "-" + pgid)
            .redirectErrorStream(true)
            .redirectOutput(Redirect.DISCARD)
            .start();
    return kill.waitFor() == 0;
}

The util-linux setsid command only calls fork() when the calling process is already a group leader; otherwise it calls setsid() in its own process and then executes the command. A child created by the JVM is not a group leader, so its PID does not change and process.pid() can be used as the ID of the new group. Passing a negative PID argument to kill sends the signal to the entire process group whose ID is the absolute value. The exception is -1, which means every process you have permission to signal rather than a group. Because kill treats arguments starting with -, such as -9 or -KILL, as signals, -- is placed before the PID so that -295952 is read as a PID. Signal number 0 sends no actual signal and only checks that the target exists and that you have permission, so if kill -0 succeeds, processes remain in the group.

waitFor() only waits for the shell, the direct child, so the shell exiting does not mean the whole group has exited. That is why killGroup() sends SIGTERM, then waits up to 5 seconds while checking with kill -0 whether any processes remain in the group, and sends SIGKILL to the whole group if some are still there. The cleanup is done in finally, always, not only on timeout. Even when the direct child exits normally, descendants started in the background can remain. For example, with a script that only runs sleep 60 &, the shell exits immediately and waitFor() returns true, but the killGroup() in finally cleans up the leftover sleep.

Output of ProcessGroupKillDemo.java

[sleep 60 | cat] pgid=295952, left=[]
[(trap '' TERM; sleep 60) & sleep 60] pgid=295959, left=[]
[setsid sleep 60 & sleep 60] pgid=296018, left=[/usr/bin/sleep 60]

The sleep and cat of the first command were in the same group as the shell, so SIGTERM ended them together. The shell of the second command ended immediately on SIGTERM, but the sleep, which was run to ignore SIGTERM, ended on SIGKILL after the 5-second grace period. Had SIGKILL been skipped on seeing only that the shell had exited, this sleep would have remained. In the third command, the sleep run under setsid moved to a new session and group, so it did not receive the signal sent to the group. When a descendant moves to a new session or a different group with setsid() or setpgid(), this method cannot clean it up. The daemon-style programs seen earlier fall into this category.

Terminating by cgroup

cgroup (control group) is a Linux kernel feature that groups processes into a hierarchy to limit and measure resources such as CPU, memory, I/O, and the number of processes. The memory limits of Docker containers also work through cgroups. A child created with fork() starts out in its parent’s cgroup, so grandchildren and all descendants below them end up in the same cgroup. setsid() changes only the session and the process group, not the cgroup. In cgroup v2, moving a process to another cgroup requires write permission on the cgroup.procs file of the common ancestor of the source and destination cgroups. So a descendant without that permission cannot escape the cgroup. The cgroup the current process belongs to can be seen in /proc/self/cgroup, and the whole tree with the systemd-cgls command.

systemd creates a separate cgroup for each service, and when it stops a service it terminates every process left in that cgroup (KillMode=control-group is the default). With systemd-run --scope, the same approach can be applied to a one-off command. The code below runs the command that escaped the process group earlier as a transient scope unit and stops that unit when the job is done.

SystemdScopeDemo.java

String unit = "job-" + UUID.randomUUID() + ".scope";
Process process = new ProcessBuilder(
        "systemd-run", "--user", "--scope", "--quiet", "--unit=" + unit,
        "sh", "-c", "setsid sleep 60 & sleep 60")
        .redirectError(Redirect.INHERIT)
        .start();
List<ProcessHandle> descendants = List.of();
try {
    if (process.waitFor(1, TimeUnit.SECONDS)) {
        System.out.println("exit=" + process.exitValue()); // a failure of systemd-run also shows up here
    } else {
        System.out.println("cgroup: " + Files.readString(Path.of("/proc/" + process.pid() + "/cgroup")).trim());
        descendants = process.descendants().toList(); // snapshot for checking the result
    }
} finally {
    int stopExit = new ProcessBuilder("systemctl", "--user", "stop", unit)
            .redirectError(Redirect.INHERIT)
            .start()
            .waitFor();
    System.out.println("systemctl stop exit=" + stopExit);
    if (!process.waitFor(10, TimeUnit.SECONDS)) {
        process.destroyForcibly().waitFor();
    }
}

List<String> left = descendants.stream()
        .filter(ProcessHandle::isAlive)
        .map(p -> p.info().commandLine().orElse("?"))
        .toList();
System.out.println("descendants=" + descendants.size() + ", left=" + left);

Output of SystemdScopeDemo.java

cgroup: 0::/user.slice/user-1000.slice/user@1000.service/app.slice/job-0fbacb17-d0c0-47de-a65d-db30d90ecfb1.scope
systemctl stop exit=0
descendants=2, left=[]

When run with --scope, systemd-run waits for the scope unit to start and then replaces its own process with the command, so the PID does not change. The command is still a direct child of the JVM, so you can read its output and wait for it to exit through Process just as in the earlier examples. The cgroup path in the output ends with job-…scope, which confirms that the command ran in a dedicated cgroup. When systemctl stop was called, both descendants ended, including the sleep that had left the group with setsid. systemctl stop sends SIGTERM first, then SIGKILL to any process that has not exited within the grace period (TimeoutStopSec). The grace period can be set on systemd-run with an option such as -p TimeoutStopSec=5s.

A scope is not tied to a specific process; it stays alive as long as at least one process remains in it. Even if the shell exits first, the scope remains active while a descendant launched in the background is still around, so the unit is always stopped in finally, as in the earlier process group example. If systemd-run fails, for example because it cannot connect to the user bus, it prints an error to stderr and exits with a nonzero exit code, so the example passes stderr through to the parent and prints the exit code. It also checks the exit code of systemctl stop and puts a time limit on waitFor() so that it does not wait forever when cleanup fails. If the command finished first and the scope is already gone, systemctl stop returns exit code 5, meaning the unit does not exist, so real code should treat that case as normal.

This approach has preconditions.

Using --user requires the user’s systemd instance to be running. For a service account on a server with no login session, either keep the user instance alive with loginctl enable-linger or use the privileged system instance.
Most containers have no systemd inside, so this approach cannot be used there. In that case, consider running a separate container per job and cleaning up at the container level.
If you have been delegated permission to manage cgroup v2 directly without systemd, you can create a cgroup for the job, start the command inside it, and then write 1 to the cgroup.kill file to send SIGKILL to every process, including those in child cgroups. This file is supported since Linux 5.14.

Whichever approach you take, the target job must be started inside that cgroup from the beginning, and the permission to move out of it must be managed together with the termination policy.

To sum up, if you control the command you run and it does not become a daemon, the process group approach is enough. If you run arbitrary scripts or commands received from outside, cleaning up by cgroup is the more reliable choice. The libraries in the next section also cut down the code for output handling and timeouts, but they do not solve all of these conditions.

Using zt-exec and Apache Commons Exec

Writing code by hand that covers everything from the previous chapter, the output pipes, EOF on stdin, timeouts, and the termination policy, is not easy. Even with a good understanding of the principles, reimplementing this code in every project is tedious. In practice, using a library that already has this handling built in is the pragmatic choice.

The representative libraries in this area are zt-exec and Apache Commons Exec. Both drain the output pipes on separate threads, and when no input is specified, a class named PumpStreamHandler closes the child process’s stdin so that the child receives EOF. zt-exec’s PumpStreamHandler class is taken from Commons Exec, to the point that the top of its source file says "This file originates from the Apache Commons Exec package". The main differences compared in this article are the shape of the API and the defaults.

zt-exec

zt-exec is a library that ZeroTurnaround, the maker of JRebel, released in 2013 after consolidating the process execution code scattered across its internal projects. Its official name is ZT Process Executor, as the title of the README says, but since the GitHub repository and the Maven artifactId are zt-exec, it is usually called zt-exec. This article uses zt-exec as well. The README explains that the goal is to provide all the functionality of ProcessBuilder and Commons Exec through a single ProcessExecutor class. Its only dependency is slf4j-api, and the minimum Java version is 8.

<dependency>
    <groupId>org.zeroturnaround</groupId>
    <artifactId>zt-exec</artifactId>
    <version>1.13.0</version>
</dependency>

The advantages of zt-exec are as follows.

The defaults are safe. Calling execute() with no configuration merges stderr into stdout and discards that output. The deadlock caused by an unread pipe does not happen with the defaults. If you need the output, turn on readOutput(true) and get a string from the result’s outputUTF8(), or pass a function that handles the output line by line to redirectOutput() as a lambda expression.
Timeouts are distinguished by exception type. When the wait in execute() exceeds the time set with timeout(), the caller receives a TimeoutException, and the worker thread attempts termination with the stopper. An invalid exit code and a timeout can be told apart by exception type alone. However, there is no guarantee that the stopper has finished terminating the process at the moment the exception is caught. The default stopper only calls destroy(), so on Linux it does not forcibly kill a process that ignores SIGTERM. The termination method can be changed with stopper(). Implement the ProcessStopper interface with a policy that calls destroy(), waits for a grace period, and then calls destroyForcibly().
Exit code checking is declarative. By default every exit code is allowed, and when you specify the allowed range with exitValueNormal() or exitValues(0, 1), any other value raises an InvalidExitValueException. The exception object’s getResult() gives access to the output up to that point, which is handy for logging the error message.
Auxiliary features are simple to configure. start().getFuture() runs the process asynchronously. However, start() ignores the timeout() setting, so you must limit the wait with something like Future.get(timeout, unit) and handle cancellation and termination separately on timeout. A timeout from get() alone does not terminate the process. destroyOnExit() requests termination of the child process from a JVM shutdown hook. redirectOutputAsInfo() can forward the output to an SLF4J logger, but this method is deprecated and redirectOutput(Slf4jStream.of(logger).asInfo()) is the recommended API.

Here is an example that runs the four commands from the previous chapter with zt-exec.

ZtExecRunner.java

static void captureOutput() throws IOException, InterruptedException, TimeoutException {
    ProcessResult result = new ProcessExecutor()
            .command("echo", "hello")
            .readOutput(true)
            .exitValueNormal()
            .execute();
    System.out.println("output=" + result.outputUTF8().trim() + ", exit=" + result.getExitValue());
}

static void largeOutput() throws IOException, InterruptedException, TimeoutException {
    AtomicLong lines = new AtomicLong();
    ProcessResult result = new ProcessExecutor()
            .command("seq", "1", "100000")
            .redirectOutput(line -> lines.incrementAndGet())
            .timeout(3, TimeUnit.SECONDS)
            .execute();
    System.out.println("seq lines=" + lines.get() + ", exit=" + result.getExitValue());
}

static void timeout() throws IOException, InterruptedException {
    try {
        new ProcessExecutor()
                .command("sleep", "60")
                .timeout(1, TimeUnit.SECONDS)
                .execute();
    } catch (TimeoutException e) {
        System.out.println("timeout: " + e.getMessage());
    }
}

static void exitValue() throws IOException, InterruptedException, TimeoutException {
    try {
        new ProcessExecutor()
                .command("ls", "/no-such-dir")
                .readOutput(true)
                .exitValueNormal()
                .execute();
    } catch (InvalidExitValueException e) {
        System.out.println("exit=" + e.getExitValue() + ", output=" + e.getResult().outputUTF8().trim());
    }
}

Here is the output. The message of the TimeoutException contains the executed command and the time limit, and the error message from ls is read with outputUTF8() thanks to the default that merges stderr into stdout. I also confirmed that no sleep process was left behind after the timeout.

Output of ZtExecRunner.java

output=hello, exit=0
seq lines=100000, exit=0
timeout: Timed out waiting for Process[pid=294823, exitValue="not exited"] to finish, timeout: 1 second, executed command [sleep, 60]
exit=2, output=ls: cannot access '/no-such-dir': No such file or directory

There are caveats as well. With readOutput(true), the thread reading the output pipe stores every byte it reads in a ByteArrayOutputStream. When the result is built, toByteArray() copies it once more, and calling outputUTF8() creates a string as well. Since ByteArrayOutputStream doubles its size when the buffer fills up, the internal buffer alone can grow larger than the output, and a string containing characters outside Latin-1, such as Korean, uses 2 bytes per character. So peak memory usage can exceed twice the size of the output.

If you do not need to keep the entire output, you can leave readOutput off and pass a line-by-line handler to redirectOutput(), as in largeOutput() above. The buffer size in this approach depends on the length of the longest line rather than the total output. Huge output with no line breaks still takes a lot of memory, and if the handler is slow, the child process’s output backs up as well. Such output is better sent to a file or to an OutputStream that works with a fixed-size buffer.

This example used SLF4J API 2.0.17, so with no implementation present, three lines of warnings including "No SLF4J providers were found" appeared during initialization. The dependency declared in the POM of zt-exec 1.13.0 is SLF4J API 1.7.32, and the warning text in that version is different. If you do not need logging, you can add the slf4j-nop that matches the SLF4J API you use to silence the warning.

Apache Commons Exec

Apache Commons Exec is a library that composes command execution, output stream handling, and timeouts from DefaultExecutor, PumpStreamHandler, and ExecuteWatchdog, respectively. Version 1.6.0, used in this article, runs on Java 8 or later and has no external dependencies. DefaultExecutor and ExecuteWatchdog are created with a builder API, and the timeout is specified as a Duration. The old constructors are marked deprecated.

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-exec</artifactId>
    <version>1.6.0</version>
</dependency>

Here is an example that runs the same four commands with 1.6.0. The PumpStreamHandler class in charge of stream handling writes to System.out and System.err by default, so to collect the output you pass your own OutputStream instances as below.

CommonsExecRunner.java

static void run(String... command) throws IOException {
    CommandLine cmdLine = new CommandLine(command[0]);
    cmdLine.addArguments(Arrays.copyOfRange(command, 1, command.length), false);
    ByteArrayOutputStream stdout = new ByteArrayOutputStream();
    ByteArrayOutputStream stderr = new ByteArrayOutputStream();
    ExecuteWatchdog watchdog = ExecuteWatchdog.builder().setTimeout(Duration.ofSeconds(1)).get();
    DefaultExecutor executor = DefaultExecutor.builder().get();
    executor.setStreamHandler(new PumpStreamHandler(stdout, stderr));
    executor.setWatchdog(watchdog);
    try {
        int exitValue = executor.execute(cmdLine);
        System.out.println(command[0] + ": exit=" + exitValue + ", stdout bytes=" + stdout.size());
    } catch (ExecuteException e) {
        System.out.println(command[0] + ": exit=" + e.getExitValue()
                + ", killed by watchdog=" + watchdog.killedProcess()
                + ", stderr=" + stderr.toString().trim());
    }
}

Output of CommonsExecRunner.java

echo: exit=0, stdout bytes=6
seq: exit=0, stdout bytes=588895
sleep: exit=143, killed by watchdog=true, stderr=
ls: exit=2, killed by watchdog=false, stderr=ls: cannot access '/no-such-dir': No such file or directory

On Linux, DefaultExecutor throws an ExecuteException for a nonzero exit code by default. The exit codes that are not treated as errors can be changed with setExitValue() or setExitValues(), and the check can be turned off with setExitValues(null). The sleep in the output above ended from the SIGTERM sent by the watchdog, so its exit code is 143. In this example, after catching the exception, watchdog.killedProcess() is used to tell whether the watchdog intervened. However, this method indicates whether destroy() was called and does not guarantee that the process actually terminated. The ExecuteWatchdog in 1.6.0 only calls destroy() on timeout and has no API for escalating to a forcible kill. If you need a forcible kill, you have to write separate code that finds the processes left after the timeout through ProcessHandle and calls destroyForcibly(). If the command ignores SIGTERM, execute() may keep waiting. Conversely, if a command that handles SIGTERM exits with an allowed code, execute() may return without an exception even after the timeout. So killedProcess() must be checked on the normal return path as well.

Maintenance Status and Recommendation

Below is the status of the two libraries as of 2026-09-06, checked against the version list on Maven Central and each project’s change log.

Item zt-exec Apache Commons Exec

Item	zt-exec	Apache Commons Exec
Latest version	1.13.0 (2026-07-10)	1.6.0 (2025-11-25)
Previous releases	1.12 (2020-09-02), 1.11 (2019-07-05)	1.5.0 (2025-05-16), 1.4.0 (2024-01-01), 1.3 (2014-11-02)
Releases in the last 5 years	1	3
Minimum Java version	8	8
Dependencies	slf4j-api	None
Default output handling	Discarded (stderr merged into stdout)	Written to `System.out` and `System.err`
Timeout notification	`TimeoutException`	Checked with `watchdog.killedProcess()` (`ExecuteException` if the exit code is a failure)
Nonzero exit code	Allowed by default, `InvalidExitValueException` when restricted with `exitValues()`	`ExecuteException` by default
Termination on timeout	`destroy()`, replaceable with `stopper()`	`destroy()` only

Latest version

1.13.0 (2026-07-10)

1.6.0 (2025-11-25)

Previous releases

1.12 (2020-09-02), 1.11 (2019-07-05)

1.5.0 (2025-05-16), 1.4.0 (2024-01-01), 1.3 (2014-11-02)

Releases in the last 5 years

Minimum Java version

Dependencies

slf4j-api

None

Default output handling

Discarded (stderr merged into stdout)

Written to System.out and System.err

Timeout notification

TimeoutException

Checked with watchdog.killedProcess() (ExecuteException if the exit code is a failure)

Nonzero exit code

Allowed by default, InvalidExitValueException when restricted with exitValues()

ExecuteException by default

Termination on timeout

destroy(), replaceable with stopper()

destroy() only

Of the two, I recommend zt-exec. Its API design has three advantages. It distinguishes timeouts from exit code errors by exception type, it takes a single method call to receive the output as a string, and its default settings avoid the deadlock caused by not reading the output pipe. Both libraries use destroy() as the default termination request. zt-exec lets you add a forcible termination policy with stopper(), but Commons Exec requires separate code.

Process Creation on Linux

Java developers running JDK 25 on Linux today can leave the jdk.lang.Process.launchMechanism option unset and keep the default, POSIX_SPAWN. It has been the default since JDK 13. To see why, this chapter first reviews the three ways Linux offers to create a process and the history of the JDK default, then looks in turn at how POSIX_SPAWN works, the memory cost and launch latency of the FORK alternative, and finally the VFORK setting to clean up when upgrading the JVM.

Three Ways to Create a Process and the History of the JDK Default

An application’s code for launching an external process passes through the JVM and ends up as a kernel system call or a C library function call. Which function call creates the child process matters because this choice has led to real production failures in the past. The classic case is a JVM with a large heap failing to allocate memory while trying to run a single external command. The 2015 NAVER D2 article Running external processes in Java (NAVER D2, 2015, in Korean) describes a Tomcat server configured with a large heap on which launching an external process failed with a Cannot allocate memory exception. The OpenJDK issue tracker also records this history. The title of JDK-6868160, which landed in JDK 7, is "(process) Use vfork, not fork, on Linux to avoid swap exhaustion". In other words, changing the call that creates the child process was a measure to avoid swap exhaustion. That you can now simply leave the default alone is the result of these problems being solved one after another.

To run another program on Linux, you pair a call that creates a child process with execve(), the system call that replaces that child with another program. The part where you have a choice is the first half, that is, how to create the child. There are three candidates.

fork(): a system call that creates a child by duplicating the parent’s address space.
vfork(): a system call that creates a child that shares the parent’s address space instead of duplicating it.
posix_spawn(): a C library function that bundles child creation and execve() together.

The Linux kernel handles the fork(), vfork(), and clone() system calls with the same function, kernel_clone(), and flags determine what is shared with the parent. In glibc 2.39 on x86-64, the environment used for this article, the fork() function invokes the clone() system call, while the vfork() function invokes the separate vfork() system call directly. Even in the same glibc 2.39, the AArch64 vfork implementation uses the clone() system call, so the call path differs by architecture. The vfork(2) manual describes vfork() as equivalent to clone() with the flags CLONE_VM | CLONE_VFORK | SIGCHLD. These flags appear in the strace output later in this chapter.

Only posix_spawn() sits at a different layer. It is a function specified by POSIX and implemented by the C library, so it has no corresponding system call; internally it picks one of the two methods above, or a clone() with the same flags as vfork(). The JDK does not implement any of the three methods itself; all three call glibc functions. You can confirm this in the dynamic symbols of libjava.so, which contains the JVM’s process creation code.

$ nm -D $JAVA_HOME/lib/libjava.so | grep -E 'posix_spawn|fork'
                 U fork@GLIBC_2.2.5
00000000000125c0 T Java_java_lang_ProcessImpl_forkAndExec
                 U posix_spawn@GLIBC_2.15
                 U vfork@GLIBC_2.2.5

T marks a symbol this file defines, and U marks a symbol it does not define and looks up in another library at run time. What OpenJDK built is the native method forkAndExec; the functions corresponding to the three launch mechanisms are all linked to glibc symbols carrying @GLIBC_ version tags. So even with the same POSIX_SPAWN setting, the actual behavior depends on the libc and its version. A JDK linked against musl rather than glibc gets musl’s implementation in the same place.

The pros and cons of the three methods are as follows.

Method Advantages Disadvantages

Method	Advantages	Disadvantages
`fork()`	The child’s address space is separate, so it can do preparation work such as cleaning up file descriptors or changing the working directory without corrupting the parent’s memory	Copy-on-write defers copying the pages, but the page tables are copied, so the larger the heap the higher the creation cost, and the call is subject to the kernel’s overcommit check
`vfork()`	The page tables are not copied, so the creation cost is nearly independent of the parent’s heap size	Behavior is undefined if the child does anything other than `execve()` or `_exit()`, and the parent’s calling thread is blocked in the meantime
`posix_spawn()`	Preparation work is handled in the way the library defines, and since glibc 2.24 it uses `CLONE_VM` to avoid copying the page tables as well	The preparation work the child can do is limited to what the library supports, and the internal implementation varies with the libc and its version

fork()

The child’s address space is separate, so it can do preparation work such as cleaning up file descriptors or changing the working directory without corrupting the parent’s memory

Copy-on-write defers copying the pages, but the page tables are copied, so the larger the heap the higher the creation cost, and the call is subject to the kernel’s overcommit check

vfork()

The page tables are not copied, so the creation cost is nearly independent of the parent’s heap size

Behavior is undefined if the child does anything other than execve() or _exit(), and the parent’s calling thread is blocked in the meantime

posix_spawn()

Preparation work is handled in the way the library defines, and since glibc 2.24 it uses CLONE_VM to avoid copying the page tables as well

The preparation work the child can do is limited to what the library supports, and the internal implementation varies with the libc and its version

That said, fork() does not mean the child may call arbitrary functions before execve() either. The fork(2) manual restricts the functions a fork()`ed child in a multithreaded program can safely call before `execve() to async-signal-safe functions. The other threads are not duplicated into the child, but the lock state those threads were holding can remain.

The vfork(2) manual describes the cost of fork() as "the time and memory required to duplicate the parent’s page tables, and to create a unique task structure for the child". This cost grows with the parent’s heap size. In the measurements later in this chapter, running one command with the FORK mechanism took 16 to 20 ms with a 256MB heap but 230 to 240 ms with an 8GB heap. The constraints on vfork() are stated even more strongly in the vfork(2) manual. Modifying any data other than the pid_t variable that holds the return value, returning from the function that called vfork(), or calling any function other than _exit() and execve() results in undefined behavior. Because the child modifies memory and a stack it shares with the parent, the outcome after the parent resumes cannot be predicted.

OpenJDK went through these three methods in turn. It used fork() at first, but when the creation cost became a problem with large heaps, JDK 7 switched the default to vfork(). The JDK, however, did preparation work between vfork() and execve(), closing file descriptors and changing the working directory, which violated the vfork() constraints we just saw. It was a choice that reduced the launch cost at the expense of safety. POSIX_SPAWN, the default since JDK 13, moves this preparation work into a separate process that does not share memory with the parent, avoiding both the copying cost of fork() and the constraint violations of vfork().

The three methods correspond to the values FORK, VFORK, and POSIX_SPAWN of the implementation-specific system property jdk.lang.Process.launchMechanism. These three values are declared in ProcessImpl.java in JDK 25, and on Linux all three can be specified, though VFORK comes with a warning. The history of the default is shown below. The JDK 27 entry is not a GA release result but what has been merged into the development build as of 2026-09-06.

JDK	Change on Linux
6	`fork()` + `execve()`
7	`vfork()` becomes the default (JDK-6868160)
12	`POSIX_SPAWN` added as an optional mechanism (JDK-8212828). Also backported to 11.0.4
13	`POSIX_SPAWN` becomes the default (JDK-8213192)
25	Specifying `VFORK` prints a deprecation warning (JDK-8357180)
27	`VFORK` removed in the development build. Specifying it prints a warning and falls back to `FORK` (JDK-8357089, CSR)

Why VFORK went away, and how to clean up any remaining setting, is covered in the last section of this chapter. The next section looks at how POSIX_SPAWN, the default since JDK 13, moves the preparation work into a separate process.

How POSIX_SPAWN Works

posix_spawn() bundles child creation, execve(), and the preparation work in between into a single call. It is similar to CreateProcess() on Windows. The JDK uses this function to first launch a small executable called jspawnhelper; jspawnhelper cleans up file descriptors and the working directory according to the settings it receives over a pipe, then `execve()`s the actual command. This structure is described in the comment at the top of ProcessImpl_md.c in the JDK 25 source.

The reason for the extra hop through the helper is the safety problem from the previous section. Doing preparation work such as closing file descriptors and changing the working directory inside jspawnhelper, which was launched by the first execve() and is therefore a separate process that does not share memory with the parent, does not violate the vfork() constraints. The same comment describes this as "moving the preparation work after the first exec to narrow the vulnerable window".

Viewed with strace, a tool that records the system calls a program makes in order, execve appears twice. Below is the process-creation-related portion of the system calls made when ProcessRunner.java, which runs echo hello, is executed with the default settings. Paths have been shortened.

$ strace -f -e trace=clone,clone3,vfork,execve -o trace.txt java ProcessRunner
$ grep -v CLONE_THREAD trace.txt | grep -E 'clone|vfork|execve'
285583 clone3({flags=CLONE_VM|CLONE_VFORK|CLONE_CLEAR_SIGHAND, exit_signal=SIGCHLD, stack=..., stack_size=0x9000}, 88 <unfinished ...>
285603 execve("$JAVA_HOME/lib/jspawnhelper", ["$JAVA_HOME/lib/jspawnhelper", "25+36-LTS", "10:11:13"], ...) = 0
285603 execve("/usr/bin/echo", ["echo", "hello"], ...) = 0

No vfork() system call appeared in this run. posix_spawn() in glibc 2.39 created the child with the clone3 system call, passing the CLONE_VM and CLONE_VFORK flags. Depending on the environment, the clone() system call may be used instead. The posix_spawn implementation in glibc 2.39 falls back to clone() if the clone3 call fails with ENOSYS or EINVAL. CLONE_VM means the child shares the parent’s address space as is, so the heap mappings and page tables are not copied. CLONE_VFORK blocks the parent’s calling thread until the child execve()`s or exits. Thanks to `CLONE_VM, the creation cost is nearly independent of heap size. The measurements later in this chapter confirm this. Running the same program with -Djdk.lang.Process.launchMechanism=FORK invokes the clone system call without the CLONE_VM flag to duplicate the address space, and execve`s `/usr/bin/echo directly without jspawnhelper.

According to the posix_spawn(3) manual, since glibc 2.24 posix_spawn() calls clone() with the CLONE_VM and CLONE_VFORK flags. It gives the child process a separate stack, blocks signals during creation, and resets the child’s handlers, reducing the risks related to the parent’s stack and signal handling. The comment in the JDK 25 source also describes the glibc 2.24 and later approach as the best choice for these reasons, and notes that musl has used this clone() approach as well. The vfork() function itself has not been removed from glibc.

The fact that jspawnhelper is a separate executable can cause trouble when updating the JDK. If you overwrite the files in the JDK path used by a running JVM, the JVM code loaded in memory and the helper version on disk diverge, and launching external commands can fail. JDK-8325621 strengthened the helper’s version check against the background of such mismatches caused by automatic updates. When updating the JDK, it is better not to overwrite the directory a running JVM uses, but to install into a new directory and switch to the new path when restarting the JVM. Helper launch errors can also have other causes, such as permission or installation problems, so check the error message and the installation state first.

The CSR for JDK-8357090 explains that FORK is kept as an alternative so that unexpected problems with posix_spawn() can be worked around. If jspawnhelper-related errors keep recurring and the cause is hard to pin down right away, you can work around them temporarily by adding -Djdk.lang.Process.launchMechanism=FORK to the JVM startup options. This choice accepts the memory burden under the overcommit policy and the launch latency covered in the next section, and it is not a setting that takes effect immediately in a running JVM.

Memory Cost and Launch Latency of FORK

If you choose FORK, you have to take into account the cost of duplicating the parent JVM’s address space. fork() creates a child process by duplicating the parent’s virtual address space as is; Linux defers the actual copying of pages with copy-on-write, but it does copy the page tables. Depending on the kernel’s memory overcommit policy, the kernel may compute in advance the memory the child might use and refuse to create it. This check applies even if the child is immediately replaced by a small program through execve().

The default value 0 of the Linux kernel setting vm.overcommit_memory, exposed through the /proc/sys/vm/overcommit_memory file, is a mode that "refuses only obvious overcommits". The kernel 5.1 code factored free memory, the page cache, free swap, and so on into this decision. If the size fork() required to duplicate the heap mappings exceeded this computed value, the call could be refused with ENOMEM, the error code meaning out of memory.

The kernel has several rules to keep this decision from becoming too strict, and they have been reinforced as versions progressed. Two examples follow.

Even on a server that strictly enforces the commit limit with vm.overcommit_memory=2, the commit check at fork() time does not unconditionally add the size of the parent’s entire address space. It counts only the size of the mappings the kernel includes in the commit total, such as private writable mappings.
The mm: fix false-positive OVERCOMMIT_GUESS failures patch, merged in kernel 5.2, simplified the mode 0 decision to "does the requested size exceed the sum of total RAM and swap". This relaxed the condition that refused to duplicate large mappings merely because free memory was low.

Even so, FORK does not always succeed. In mode 2, large anonymous private writable mappings such as the Java heap count toward the cost, so process creation fails if the remaining commit limit is exceeded, and even in mode 0 the actual allocation of kernel memory such as page tables can fail.

Even when creation is not refused, the time cost remains. Although the overcommit decision was relaxed, the fact that fork() copies the page tables has not changed. The copying cost varies with factors such as the heap area actually touched and the page size. POSIX_SPAWN, by contrast, shares the address space through CLONE_VM, so there is no such copying. I measured, for each launch mechanism, the time taken to run the true command 30 times with the heap preallocated. The measurement code is SpawnBench.java; I set -Xms and -Xmx to the same value and pre-touched the heap with the -XX:+AlwaysPreTouch option before measuring. Each run averaged 30 iterations of start().waitFor() after 5 warm-up iterations, so the figures include running the command and waiting for it to exit, not just the pure creation time. Below are the values from two runs at the time of writing.

Heap size	POSIX_SPAWN (ms/run)	FORK (ms/run)
256MB	1.5, 1.2	15.9, 20.2
2GB	1.6, 1.9	120.8, 140.7
8GB	2.0, 2.1	243.5, 231.2

In this measurement, POSIX_SPAWN stayed in the range of about 1 to 2 ms, while FORK slowed down as the heap grew, differing by more than 100 times at 8GB. This does not mean the cost is exactly proportional to heap size or that this ratio appears in every environment. A re-measurement on 2026-09-06 confirmed the same trend, but the absolute times differed.

In the FORK mechanism, dup_mmap() in Linux 6.17, which duplicates the address space, copies the mappings and page tables while holding the parent process’s address space lock (mmap_lock) in write mode. Meanwhile, other threads attempting memory mapping changes that need this lock have to wait. For a web application that runs external commands synchronously while handling requests, this cost can add to the response time. Unless you are temporarily working around a jspawnhelper problem, there is currently no reason to accept these drawbacks and change the default to FORK.

Removing the VFORK Setting When Upgrading the JVM

When upgrading the JVM to version 25 or later, it is best to remove any remaining -Djdk.lang.Process.launchMechanism=VFORK setting. The places where this setting may still linger are JVM launch scripts, JAVA_OPTS in Dockerfiles, and application server startup options. JDK 25 prints a warning, and with the change merged into the JDK 27 development build the setting is replaced by FORK, which can increase launch latency with large heaps.

Because vfork() was the default on Linux from JDK 7 through 12, some projects wrote this property explicitly to preserve the previous behavior when the default changed to POSIX_SPAWN in JDK 13. Even in environments where glibc was older than 2.24 at the time, there was no need to specify this value. According to the comment in the JDK 13 source, posix_spawn() in glibc 2.4 through 2.23 chooses between fork() and vfork() depending on the call arguments, and the way the JDK calls it meets the conditions for using vfork(). From glibc 2.24 onward, it changed to the clone()-based implementation with the separate stack and signal handling described earlier. There is no reason to specify this value today, so remove the property and return to the default.

JDK 7’s choice of vfork() as the default was controversial even at the time. vfork() is not a standard function. The STANDARDS section of the vfork(2) manual says "None", and the HISTORY section notes that this function, which appeared in 3.0BSD, was marked OBSOLETE in POSIX.1-2001 and had its specification removed in POSIX.1-2008. 4.4BSD made vfork() simply identical to fork(), and Linux also behaved the same as fork() until around 2.2.0-pre6, becoming an independent system call from 2.2.0-pre9. Still, what went away is not the kernel’s vfork() but the JDK’s VFORK mode. It was not because it was dropped from the standard, nor because the kernel changed, but because, as we saw earlier, the work the JDK itself did between vfork() and execve() was unsafe.

Specifying this option in JDK 25 prints the following warning to standard error.

$ java -Djdk.lang.Process.launchMechanism=VFORK ProcessRunner
VFORK MODE DEPRECATED
The VFORK launch mechanism has been deprecated for being dangerous.
It will be removed in a future java version. Either remove the
jdk.lang.Process.launchMechanism property (preferred) or use FORK mode
instead (-Djdk.lang.Process.launchMechanism=FORK).

The examples and measurements in this article are based on JDK 25. When applying them to older JDKs, check the launch mechanism and the range of API support separately. For example, OpenJDK 11u can specify POSIX_SPAWN as an option from 11.0.4 on, but its default is vfork(), and the Linux implementation in OpenJDK 8u does not support this option as of 2026-09-06.

Conclusion

Code that launches external processes must be designed with output handling, timeouts, and a termination policy together. If you do not need to process the output, use Redirect.DISCARD or inheritIO(); if you need stdout and stderr separately, read both streams concurrently. For commands that read stdin, close the stream after writing all the input so the command receives EOF. After a timeout, take care not only of the termination request but also of whether to kill forcibly and of resource cleanup.

zt-exec and Commons Exec reduce this code. Compare their defaults for output and exit codes, how they signal a timeout, and their dependencies, and pick the one that fits your project. Neither library guarantees forcible termination with the default destroy() alone, and for cleaning up descendants you can send a signal to the processes remaining in the same group or terminate by cgroup.

With JDK 25 on Linux, keeping the default POSIX_SPAWN is the safe choice.

References

JDK documentation
- Process (Java SE 25)
- ProcessBuilder (Java SE 25)
- Runtime (Java SE 25): why the exec(String) overloads are deprecated
- Runtime.java (JDK 25+36): the implementation of exec() delegating to ProcessBuilder
- ProcessImpl_md.c (JDK 25+36): comments explaining the pros and cons of each launch mechanism and the posix_spawn() implementations in glibc and musl
Libraries
- ZT Process Executor (zt-exec): usage examples in the README
- ZT Process Executor CHANGELOG: the changes in 1.13.0 and its release date
- Apache Commons Exec
- Apache Commons Exec Changes: the builder API and the introduction of Duration since 1.4.0
OpenJDK issues
- JDK-6868160 (process) Use vfork, not fork, on Linux to avoid swap exhaustion
- JDK-8212828 (process) Provide a way for Runtime.exec to use posix_spawn on linux
- JDK-8213192 (process) Change the Process launch mechanism default on Linux to be posix_spawn
- JDK-8357180 Deprecate VFORK launch mechanism from Process implementation (linux)
- JDK-8357090 Remove VFORK launch mechanism from Process implementation (linux)
- JDK-8357089 implementation commit: the removal of VFORK and its replacement with FORK in the JDK 27 development build
- JEP 486: Permanently Disable the Security Manager
Linux manuals and kernel
- pipe(7): pipe capacity
- setsid(1): running without forking when not a group leader
- setsid(2), kill(1) (procps-ng), kill(2): creating a new session, signaling a group with a negative PID, checking existence with signal 0
- PR_SET_CHILD_SUBREAPER(2const): reparenting to a subreaper
- Control Group v2: permission to move processes and cgroup.kill
- systemd-run(1), systemd.kill(5): running as a scope unit and KillMode
- vfork(2)
- posix_spawn(3): the implementation since glibc 2.24
- Overcommit Accounting
- Linux 5.2 mm/util.c: the mode 0 decision in __vm_enough_memory()
- Linux 6.17 mm/mmap.c: the locking and page table duplication in dup_mmap()
- mm: fix false-positive OVERCOMMIT_GUESS failures: the kernel 5.2 patch that changed the heuristic
When Runtime.exec() won’t: Michael Daconta’s article from 2000
Running external processes in Java (NAVER D2, 2015, in Korean): the memory problem with fork() and the background to the adoption of vfork() in JDK 7
Example code for this article

IEEE 754 Floating-Point Errors and Alternatives in Java

Sat, 3 Oct 2026 00:00:00 +0000

Table of Contents

1. Floating-Point Errors in Code
2. Bit Layout of double (IEEE 754 binary64) and How 0.1 Is Stored
3. Failures Caused by Binary Representation Errors
- 3.1. The 2011 NEIS Grading Error
- 3.2. The 1991 Gulf War Patriot Missile Failure
4. Alternatives in Java for Avoiding Decimal Arithmetic Errors
- 4.1. Calculating with BigDecimal
- 4.2. Calculating with Integers
5. Choosing Between BigDecimal and Integer Calculation
6. Domain-Specific Libraries for Money and Units
- 6.1. Java Money (JSR 354)
- 6.2. Other Domain-Specific Libraries
7. References

Java’s double and float types store values in binary according to the IEEE 754 floating-point standard. In this format, the decimal number 0.1 cannot be represented exactly. In binary, 0.1 is an infinitely repeating fraction, so fitting it into a finite number of bits requires rounding it to the nearest representable value. This article explains why such errors occur and when they become dangerous, using real failures as examples, and then summarizes the alternatives available in Java.

1. Floating-Point Errors in Code

You can see floating-point errors quickly in jshell, the interactive tool included with the JDK since JDK 9.

Adding decimals

jshell> 0.1 + 0.2
$1 ==> 0.30000000000000004

jshell> 0.1 + 0.2 == 0.3
$2 ==> false

jshell> 1.03 - 0.42
$3 ==> 0.6100000000000001

Adding 0.1 ten times does not give 1.0.

Adding 0.1 ten times

jshell> double sum = 0;
sum ==> 0.0

jshell> for (int i = 0; i < 10; i++) { sum += 0.1; }

jshell> sum
sum ==> 0.9999999999999999

The BigDecimal constructor reveals the value actually stored for the double literal 0.1.

The actual value of the double literal 0.1

jshell> new BigDecimal(0.1)
$1 ==> 0.1000000000000000055511151231257827021181583404541015625

I typed 0.1 at the jshell prompt, but the stored value is greater than 0.1 by about 5.55 × 10^-18.

This error is not specific to Java. JavaScript’s number type also uses the IEEE 754 binary64 format, so entering the same expressions in the Chrome DevTools console gives the same results.

The next section follows the bit layout of double to show why these values are stored.

2. Bit Layout of double (IEEE 754 binary64) and How 0.1 Is Stored

IEEE 754 is a standard that defines several floating-point formats. Java uses two of them.

Format 1985 name Size Java type

Format	1985 name	Size	Java type
binary32	single	32 bits (sign 1 / exponent 8 / fraction 23)	`float`
binary64	double	64 bits (sign 1 / exponent 11 / fraction 52)	`double`

binary32

single

32 bits (sign 1 / exponent 8 / fraction 23)

float

binary64

double

64 bits (sign 1 / exponent 11 / fraction 52)

double

The first version of the standard, IEEE 754-1985, called these two formats single and double. The 2008 revision renamed them binary32 and binary64, and these names carry over to the current standard, IEEE 754-2019. The standard also defines binary16, binary128, and the decimal formats decimal32, decimal64, and decimal128.

The binary formats of IEEE 754 convert a real number to binary scientific notation and then store it as bits. In decimal scientific notation, you shift the decimal point so that the integer part is a single digit from 1 to 9, and express the number of places shifted as a power of 10. For example, 0.001 is written as 1.0 × 10^-3. Binary works the same way: you multiply or divide by 2 until the integer part is a single digit, that is, until the value is at least 1 and less than 2. The only nonzero digit in binary is 1, so the normalized result always takes the form ±1.fraction × 2^exponent. For example, binary 0.011 (decimal 0.375) is written as 1.1 × 2^-2.

A double (binary64) stores this normalized value in 64 bits according to the following rules.

The sign (s) is stored in the first bit. 0 means positive and 1 means negative.
The exponent (e) is stored in 11 bits as the actual exponent plus 1023. This lets exponents from -1022 to 1023 be stored as unsigned integers from 1 to 2046; reading the value subtracts 1023 again. Of the values 0 to 2047 that 11 bits can hold, the two at either end are reserved: 0 represents zero and numbers very close to zero, and 2047 represents infinity and NaN.
The fraction (f) stores only the part after the binary point of 1.fraction, in 52 bits. The integer part of a normalized number is always 1, so that 1 is omitted.
If the part after the binary point exceeds 52 bits, it is rounded to the nearest value.

The figure below shows 0.1 stored according to these rules. The 64 bits are divided into a 1-bit sign, an 11-bit exponent, and a 52-bit fraction.

Let’s follow the conversion in the lower half of the figure. Multiplying 0.1 by 2 repeatedly gives 0.2, 0.4, and 0.8, and on the fourth step it becomes 1.6, which is the first value at least 1 and less than 2. Since multiplying by 2 four times gave 1.6, 0.1 = 1.6 ÷ 2⁴ = 1.6 × 2^-4. The sign bit is therefore 0, and the exponent field is -4 + 1023 = 1019. The fraction is the problem. Converting 0.6 to binary gives 0.1001 1001 1001…, with 1001 repeating forever. Fitting it into 52 bits requires rounding. The bits following the first 52 are 1001…, so the discarded part is more than half of the last bit’s weight. The value is therefore rounded up, and the last four bits of the fraction change from 1001 to 1010. As a result, what gets stored is not 0.1 but a number very slightly greater than 0.1. The value 0.1000000000000000055511151231257827021181583404541015625 seen earlier with new BigDecimal(0.1) is exactly this rounded value.

You can see the stored bits in hexadecimal in jshell.

The 64 bits that store 0.1

jshell> Long.toHexString(Double.doubleToLongBits(0.1))
$1 ==> "3fb999999999999a"

One hexadecimal digit is 4 bits. The first three digits, 3fb, are the 12 bits of the 1-bit sign and the 11-bit exponent combined: the sign bit is 0 and the exponent field is 0x3fb, or 1019 in decimal. The remaining thirteen digits are the 52-bit fraction. The digit 9 (1001) repeats twelve times, and only the last digit is rounded up to a (1010).

Not every decimal fraction has this error. Fractions whose denominator is a power of 2, such as 0.5 (1/2), 0.25 (1/4), and 0.75 (3/4), are finite binary fractions, so they are stored exactly as long as they need no more than 53 significant bits. In contrast, a decimal fraction whose reduced denominator contains a factor of 5, such as 0.1 = 1/10, becomes an infinitely repeating binary fraction and cannot avoid rounding error. For more detail on the standard, see the Wikipedia article on IEEE 754.

3. Failures Caused by Binary Representation Errors

In fields that deal with approximations, such as data from scientific experiments, these errors often fall within an acceptable range. But where values must be exactly equal, such as money and grades, or where errors accumulate across calculations, even a tiny error becomes a critical bug. Let’s look at two cases, one in Korea and one abroad, where such errors led to real failures.

3.1. The 2011 NEIS Grading Error

In July 2011, a grade-processing error in NEIS, the next-generation National Education Information System of South Korea, changed the end-of-semester class ranks of about 29,000 students at 823 high schools nationwide. It happened just before the early-admission season for universities, so the impact was large.

NEIS computed a semester total by adding written exam scores and performance assessment scores. The ranks of students with the same total were decided by a tie-breaking rule that each school chose from 45 options (Yeongnam Ilbo article, in Korean). For example, at a school that gives priority to written exam scores, student A with 65 on the written exam and 25 on performance assessments ranks ahead of student B with 60 and 30, even though both have a total of 90. Detecting ties is an important step in computing ranks; schools even had to choose a tie-breaking rule in advance.

NEIS was programmed to display totals to 16 decimal places, and some values had a stray '1' appearing irregularly in those decimal places. This is the same pattern as 1.03 - 0.42 producing 0.6100000000000001 at the beginning of this article. For example, if two students' totals are computed as 90 and 90.00000000000001, the values are not equal, so a direct comparison treats the two students as not tied and sorts the one with the error as having a higher score. As a result, students who should have had the same total were not detected as tied, or the ranks among tied students were reversed (notice from the Ulsan Metropolitan Office of Education, in Korean). The Ministry of Education, Science and Technology explained that the bug was caused by not correcting this calculation error (Kyunghyang Shinmun article, in Korean).

jshell shows that adding the same numbers in a different order can produce a different sum. The following is not NEIS’s actual formula, only an illustration of the principle.

Sums that depend on the order of addition

jshell> 0.1 + 0.2 + 0.3
$1 ==> 0.6000000000000001

jshell> 0.3 + 0.2 + 0.1
$2 ==> 0.6

jshell> (0.1 + 0.2 + 0.3) == (0.3 + 0.2 + 0.1)
$3 ==> false

Both sums add the same three numbers and should be equal, but with double they produce different values and are not detected as a tie.

According to the Ministry’s count, the ranks of 29,007 students at 823 high schools changed, and for 2,416 students at 350 of those schools, the rank grade changed as well (Jeju Ilbo article, in Korean). Schools had to recompute grades with an error-correction program and reissue report cards (Kyunghyang Shinmun article).

The results of an inspection the Ministry’s special task force announced in September of the same year identify the type in which the error occurred. According to the report, while the old NEIS programs were being redeveloped for the next-generation NEIS, the team failed to anticipate arithmetic errors with floating-point (Double) data that arise from the characteristics of the newly installed database (DB2), and this caused the grading errors (Electronic Times article, in Korean). In other words, grades were computed with the DB2 DOUBLE type. The DOUBLE type in Db2 for Linux, UNIX, and Windows is 64 bits with the same range as IEEE 754 binary64, so it has the same kind of error as Java’s double. Some programs were missing the 'error correction code' that was supposed to fix that error, and the ranks were reversed in those programs (Yonhap News article, in Korean).

At the time, network developer Lee Kyung-moon pointed out in a DailySecu article (in Korean) that the problem was using floating point where exact numeric representation was required. He argued that rather than correcting the error, the design should have switched to integer processing or a type that supports arbitrary precision. Integer minor units and BigDecimal, introduced later in this article, are exactly those two options. The incident shows that handling values with decimal arithmetic, such as grades, in floating point can break comparisons such as tie detection.

3.2. The 1991 Gulf War Patriot Missile Failure

The fact that 0.1 cannot be represented as a finite binary fraction has also cost lives. On February 25, 1991, during the Gulf War, an Iraqi Scud missile struck a US Army barracks in Dhahran, Saudi Arabia, killing 28 American soldiers and injuring 99 (US Army article). A Patriot missile battery was deployed at the base to intercept such attacks, but it did not even attempt an interception.

Chapter 1 of the Korean book Software Errors in History (Acorn Publishing, 2014), titled "28 Lives Taken by an Error of 0.000000095," explains the cause of the incident based on the US GAO’s investigation report. The Patriot system counted time in tenths of a second to predict where a target would appear, and converted the count to seconds by multiplying it by 0.1 stored in a 24-bit fixed-point register. Because 0.1 is an infinitely repeating binary fraction, everything beyond 24 bits was truncated, and an error of about 0.000000095 seconds accumulated every tenth of a second. After 20 hours of continuous operation, the computed time was 0.0687 seconds behind the actual time; after about 100 hours, as with the battery at the time of the incident, it was 0.3433 seconds behind. By the GAO report’s calculation, this timing error shifted the range gate where the system looked for the target by 687 meters. The tracking radar searched an area that far from the missile’s actual position. The radar found no target there, so no interceptor was launched, and the Scud hit the barracks.

This system used fixed-point arithmetic, not floating point like double. But the principle is the same as in this article: 0.1 could not fit into a finite number of binary digits, and the error accumulated.

4. Alternatives in Java for Avoiding Decimal Arithmetic Errors

This section introduces two ways to avoid the errors of double arithmetic: using BigDecimal, and handling amounts as integers in the smallest unit.

4.1. Calculating with BigDecimal

The standard way to handle decimal fractions exactly in Java is java.math.BigDecimal. Why You Should Never Use Float and Double for Monetary Calculations also recommends BigDecimal instead of floating-point types for monetary calculations.

Addition and subtraction with BigDecimal

jshell> new BigDecimal("0.1").add(new BigDecimal("0.2"))
$1 ==> 0.3

jshell> new BigDecimal("1.03").subtract(new BigDecimal("0.42"))
$2 ==> 0.61

There is one catch. If you pass a double to the constructor, the rounding error introduced when the decimal fraction was stored in the double carries over into the BigDecimal. As shown earlier, new BigDecimal(0.1) holds the approximation stored in the double, not 0.1. To avoid this error, use the constructor that takes a string, or BigDecimal.valueOf(). BigDecimal.valueOf(0.1) builds the value from the string "0.1" returned by Double.toString(0.1), so it is 0.1. However, valueOf() cannot remove an error that already exists in a value computed as a double. BigDecimal.valueOf(0.1 + 0.2) is 0.30000000000000004.

Using BigDecimal does not decide the rounding policy for you. A division whose decimal expansion does not terminate, such as 1 divided by 3, throws an exception unless you specify the scale and the rounding mode.

Non-terminating division with BigDecimal

jshell> new BigDecimal("1").divide(new BigDecimal("3"))
|  Exception java.lang.ArithmeticException: Non-terminating decimal expansion; no exact representable decimal result.

jshell> new BigDecimal("1").divide(new BigDecimal("3"), 10, RoundingMode.HALF_UP)
$1 ==> 0.3333333333

java.math.RoundingMode, used here, is an enum for choosing how to round: whether to round 0.5 up (HALF_UP), to the nearest even number (HALF_EVEN), or to always discard the fraction (DOWN). For example, rounding 2.5 and 3.5 to integers gives 3 and 4 with HALF_UP, 2 and 4 with HALF_EVEN, and 2 and 3 with DOWN. What BigDecimal eliminates is the error that comes from binary representation. How many decimal places to keep and how to round them is a rule the team must decide and follow according to the needs of the domain.

Joshua Bloch makes the same recommendation in Item 60 of Effective Java, 3rd edition, "Avoid float and double if exact answers are required." The item suggests int and long as well as BigDecimal; the section on choosing between them below covers which to pick.

4.2. Calculating with Integers

Handling amounts as integers in the smallest unit, such as won or cents, is also common. The API of the payment service Stripe is an example. The amount attribute of the Charge object is an integer, described as follows.

A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).

— Stripe API Reference
The Charge object

This is especially practical for the Korean won, where amounts below 1 won have little value, as long as it does not conflict with business rules. For the same reason, existing systems in Korea often define won amounts as integer columns in the database. So even if the application calculates with BigDecimal, there is at least one conversion to an integer right before the value is stored. An example from the Woowa Brothers tech blog post Writing Test Code with Spock (in Korean) shows this approach. It uses BigDecimal for rounding, but the amount parameter amount and the return type are long.

calculate method from the Spock example

public static long calculate(long amount, float rate, RoundingMode roundingMode) {
    return BigDecimal.valueOf(amount * rate * 0.01)
            .setScale(0, roundingMode).longValue();
}

The amount itself stays an integer, and right after the rate calculation, which produces a fraction, the method returns to an integer through a BigDecimal with an explicit rounding mode.

However, once a floating-point type is mixed in, as in amount * rate * 0.01, the calculation becomes floating-point arithmetic. The long value is converted to float and the multiplication is done in float, losing precision, so errors can occur even though the amount parameter and the return type are integers.

Limits of the calculate method

jshell> calculate(16_777_217L, 100f, RoundingMode.HALF_UP)
$1 ==> 16777216

jshell> calculate(671_089L, 50f, RoundingMode.HALF_UP)
$2 ==> 335544

The first call multiplies by 100%, so it should return 16,777,217 unchanged, but the result is 1 won short. A float has 24 bits of precision (a 23-bit fraction plus the implicit leading bit), so it cannot represent every integer above 2²⁴ (16,777,216); 16_777_217L becomes 16,777,216 the moment it is converted to float. The second call should return 335,545, which is 50% of 671,089 won (335,544.5 won) rounded, but it is 1 won short. The amount is less than 2²⁴, but the product with the rate, 33,554,450, exceeds 2²⁴ and is stored in a float as 33,554,448. Even if the inputs stay integers, a single floating-point step in the middle of the calculation brings the error back.

If you modify the quoted example to move the rate into BigDecimal as well, the result is 16,777,217 as expected.

Version with the multiplication moved into BigDecimal

public static long calculate(long amount, BigDecimal percent, RoundingMode roundingMode) {
    return BigDecimal.valueOf(amount)
            .multiply(percent)
            .movePointLeft(2)
            .setScale(0, roundingMode)
            .longValueExact();
}

Result of the fixed calculate method

jshell> calculate(16_777_217L, new BigDecimal("100"), RoundingMode.HALF_UP)
$1 ==> 16777217

The longValueExact() call on the last line throws an ArithmeticException if the result exceeds the range of long. In that case, longValue() silently returns only the low-order 64 bits, so a wrong amount could be stored.

Even with integer minor units, eliminating errors requires keeping every intermediate value as an integer or a BigDecimal.

5. Choosing Between BigDecimal and Integer Calculation

For a module where calculation precision matters, I recommend at least keeping double and float out of method parameters and return types. The two alternatives are BigDecimal and integer minor units (long), both covered above. long is better for performance and concise code. BigDecimal is better at preventing developer mistakes.

Item 60 of Effective Java, mentioned earlier, frames the choice the same way. Its conclusion is to use BigDecimal if you want the system to keep track of the decimal point and want control over rounding, accepting that it is less convenient and slower than primitive types. It also offers the alternative of using int or long if performance matters and you can keep track of the decimal point yourself, which is the integer approach from the previous section. It adds a rule of thumb based on the number of digits: use int if the values do not exceed nine decimal digits, long if they do not exceed eighteen, and BigDecimal beyond that.

Peter Lawrey of Chronicle Software lists the drawbacks of BigDecimal in If BigDecimal is the answer, it must have been a strange question.

The syntax is unnatural. You chain method calls instead of using operators, which makes formulas harder to read.
It uses more memory than double. It keeps creating objects, which produces a lot of garbage.
It is much slower for most operations.

The post also includes a JMH benchmark measuring the speed difference. The benchmark repeatedly computes the average of two values, rounded to six decimal places, over an array of 1,024 elements.

Table 1. Lawrey’s JMH benchmark results
Benchmark	Throughput (ops/s)	Error
`doubleMidPrice`	123,208.083	±2,109.738
`bigDecimalMidPrice`	23,638.568	±590.094

The double implementation has about 5.2 times the throughput of the BigDecimal one. These numbers were measured in 2014 and may differ on current JVMs. The comparison is against double, not directly against long.

Lawrey’s conclusion is to use BigDecimal if you do not know how to handle rounding with double or if your project standards require it, but, if you have a choice, not to assume that BigDecimal is automatically the right answer. He cites his own experience: when he is brought in to tune the performance of a financial application, he eventually ends up removing BigDecimal. BigDecimal is not the biggest source of latency at first, but as other bottlenecks get fixed, it eventually becomes the slowest part. In the comments, he adds that trading and financial systems existed before BigDecimal, and that many were built in C++ without a decimal type.

Integer minor units have the advantage of using few system resources. A long value requires no object creation, and its arithmetic is plain CPU integer arithmetic. Memory size can be measured with JOL (Java Object Layout). With the default settings of the 64-bit JDK 25 HotSpot VM, a new BigDecimal("1.03") object is 40 bytes. When the value exceeds the range of long, a BigInteger and an int array are added internally, so the 22-digit new BigDecimal("12345678901234567890.12") takes 112 bytes in total. A long value is 8 bytes.

On the other hand, the long approach requires developers to pay more attention to correctness when a calculation involves division or mixes in double or float. BigDecimal also requires a rounding rule, but with long, an error caused by a missing rule is harder to notice. When the rounding mode is missing from a division that does not terminate, BigDecimal throws an exception as shown earlier, but long division silently discards the fraction. For example, 10 / 3 is 3. And because long uses the basic arithmetic operators, the compiler does not stop floating point from creeping in, as with amount * rate * 0.01 in the calculate() example. The whole system must also follow the same rule about what the smallest unit is, a burden that BigDecimal does not have.

The following table summarizes the comparison.

Table 2. Comparison of BigDecimal and integer calculation
Type	Representation	Strengths	Trade-offs
`BigDecimal`	Arbitrary-precision integer and a scale	Represents decimal numbers exactly, with as many digits as needed No need to decide separately how many places to scale to an integer	Higher memory use (40 bytes or more per object in the measurement above) Slower arithmetic Arithmetic through chained method calls instead of operators
`long`	Integer converted to the smallest unit	Low memory use with no object creation Fast, using CPU integer arithmetic	Errors occur if `double` or `float` slips into intermediate calculations The whole system must follow the smallest-unit rule

Once you decide which type to use, write it down as a simple rule that everyone on the team can understand. For example: "Handle amounts as long (in won) in every layer, compute only ratios with BigDecimal, and truncate with RoundingMode.DOWN." The developers responsible for a system keep changing. You cannot assume that everyone understands the principles behind the errors discussed in this article. A clear and simple rule makes it more likely that newly assigned developers follow the same approach. This keeps decimal arithmetic consistent across all modules and reduces the chance that code with critical errors gets in. So I suggest also judging a candidate rule by whether you can write it down concisely and clearly.

After setting a rule, you also need to fix existing code that violates it to keep things consistent from then on. But code that already works and handles money directly is scary to change. That is why an approach, once established, often stays unchanged. Even if only to prepare for changing existing code someday, separate logic that handles sensitive numbers such as money into its own method, like calculate() above. Then you can test it with only inputs and expected results, without a database or external systems. A structure that is easy to test catches not only decimal errors but also logic errors in newly added code early.

6. Domain-Specific Libraries for Money and Units

The two approaches above are choices about how to hold a number. On top of them, there are domain-specific libraries that wrap values with units, such as money, time, and physical quantities, in dedicated types. Money libraries hold the number internally as either a BigDecimal or integer minor units. Java Money is a representative example.

6.1. Java Money (JSR 354)

Java Money is an API for handling monetary amounts together with currencies, standardized as JSR 354. It represents an amount and its currency together with the MonetaryAmount interface. The JCP proposal considered including it in Java SE 9, but it was never added to the JDK. To use it, you add the API (javax.money) and its reference implementation, Moneta, as separate dependencies.

build.gradle

implementation 'org.javamoney:moneta:1.4.5'

The Money implementation calculates with BigDecimal internally, so 1.03 - 0.42, which gave 0.6100000000000001 with double at the beginning of this article, comes out as exactly 0.61.

Subtraction with Money

MonetaryAmount price = Money.of(new BigDecimal("1.03"), "USD");
MonetaryAmount result = price.subtract(Money.of(new BigDecimal("0.42"), "USD"));
System.out.println(result); // USD 0.61

Arithmetic between amounts in different currencies throws javax.money.MonetaryException. The API stops the mistake of mixing amounts in different currencies with an exception at run time.

Adding amounts in different currencies

price.add(Money.of(100, "KRW")); // MonetaryException: Currency mismatch: USD/KRW

Java Money does not replace the two approaches above; it sits on top of them. Two of the main MonetaryAmount implementations in Moneta map directly to the two numeric representations discussed in this article.

Money: Stores the amount as a BigDecimal, and so carries the costs of BigDecimal summarized above.
FastMoney: Stores the amount in a single long in minor units. The scale is fixed at five decimal places, so the largest representable amount is about 92 trillion (Long.MAX_VALUE / 10⁵). In exchange for this limit it is fast; its Javadoc says it is 10 to 15 times faster than Money.

Because they share an interface, you can swap Money for FastMoney if speed becomes a problem. Even with a domain type, you still need to decide on the numeric representation, and the trade-offs from the previous section reappear as the choice of implementation.

In my view, whether to adopt Java Money depends on whether you handle multiple currencies. With a single currency, plain BigDecimal or long values are enough; in a system that mixes currencies, having the API catch currency mismatches is worth the extra dependency. For more usage examples, see Java Money and the Currency API on Baeldung.

6.2. Other Domain-Specific Libraries

Java Money is not the only library that wraps numeric representations in domain types.

Joda-Money: A money library that predates Java Money. The Money class stores the amount as a BigDecimal with the scale fixed to the currency’s default number of decimal places (2 for the dollar, 0 for the yen), while the BigMoney class allows any scale.
Units of Measurement API (JSR 385): Represents physical quantities such as length and mass, together with their units, as types. The API package is javax.measure, and the reference implementation is Indriya. Just as a currency mismatch throws an exception for money, it catches calculations with mismatched kinds of quantities, and when the generic types are fixed, it catches them at compile time. For example, code that adds a Quantity<Mass> to a Quantity<Length> does not compile because the generic types differ. Preventing unit errors is a separate matter from calculating values exactly, however. Values are accepted as Number, so a quantity created from a double keeps its floating-point error.
java.time.Duration: An example built into the JDK rather than an extra dependency. It stores a length of time in two fields, seconds (long) and nanoseconds (int). It applies the same technique as integer minor units, in that it does not hold fractional seconds in a single double.

Even if none of these libraries fits, a type you build within your own system can play the same role. In that case too, decide whether to hold the number as a BigDecimal or an integer by the criteria described in this article. And make sure float or double cannot slip into intermediate calculations.

7. References

IEEE 754 - Wikipedia
Joshua Bloch, Effective Java, 3rd edition, Addison-Wesley, 2018, Item 60
Why You Should Never Use Float and Double for Monetary Calculations
BigDecimal Class in Java - GeeksforGeeks
If BigDecimal is the answer, it must have been a strange question - Peter Lawrey
Writing Test Code with Spock - Woowa Brothers Tech Blog (in Korean)
The Charge object - Stripe API Reference
JOL (Java Object Layout)

Failure Cases

NEIS grading error (all in Korean)
Patriot missile failure
- Kim Jong-ha, Software Errors in History (in Korean), Acorn Publishing, 2014, pp. 25-35
- Patriot Missile Defense: Software Problem Led to System Failure at Dhahran, Saudi Arabia - GAO (1992-02)
- Scud Alert: After the Blast - DVIDS

Benelog Tech Notes

Call by Value vs. Call by Reference

Call by Value and Call by Reference

The Terms "Pass by" and "Call by"

Call by Sharing

Java

Result of the swap Method

Why Reassigning a Parameter Does Not Affect the Caller’s Variable

Mutating Object State: The Source of the Misconception

Java References and Terminology Confusion

A New Frame for Every Method Invocation

Kotlin

JavaScript

The By Reference Wording in JavaScript: The Definitive Guide

C

C++

Pointer Parameters vs. Reference Parameters

References in the C++ Standard

C#

Python

Go

Rust

Ada: Call by Reference vs. Copy-Restore

Summary

References

VO vs. DTO: Definitions and the History of Conflating the Terms

Definition of Value Object

The Status of Immutability: Definitional Requirement vs. Good Design

Definition of DTO (Data Transfer Object)

VO in the First Edition of Core J2EE Patterns and TO in the Second

The Cost of Calling a Data Carrier a VO

References

Value Object

Transfer Object / DTO

Documenting and Verifying Thread Safety: Javadoc, Annotations, Static Analysis, and ArchUnit

Thread Safety in Javadoc

Why Javadoc Hides synchronized

The Need for a Class-Level Thread Safety Statement

The Five Levels of Thread Safety in Effective Java

Examples in Class Descriptions

java.util.LinkedList

java.text.SimpleDateFormat

org.springframework.batch.item.file.FlatFileItemWriter

Thread Safety with Annotations

@Contract in Apache HttpClient

JCIP Annotations

Annotations Spread Under the JCIP Names

Choosing Annotations for Your Purpose

What Static Analysis Tools Check

SpotBugs

Error Prone

Checking @GuardedBy

Checking @Immutable

Checking @ThreadSafe

IntelliJ IDEA

Project-Specific Rules Verified with ArchUnit

Example Code

Rules and Results

Summary

References

MySQL JDBC Configuration for High-Performance Batch Jobs

Using Server-Side Prepared Statements

Improving Batch Update Performance

Options for Large-Scale Data Retrieval

Streaming Results One Row at a Time

Using Server-side Cursors

References

Running External Processes from Java: JDK 25 on Linux 6.x

Pitfalls of Launching External Processes with the JDK Classes

ProcessBuilder vs. Runtime.exec

Limits of the ProcessBuilder Defaults

Handling the stdout and stderr Pipes

Deadlock from an Unread Pipe Buffer

Reading Both Streams Concurrently

Redirecting Output the Java Process Will Not Read

Closing stdin and EOF

Timeouts and Termination Policy

Cleaning Up Descendant Processes

Cases Where Descendants Are Left Behind

Terminating by Process Group

`ProcessBuilder` vs. `Runtime.exec`

Limits of the `ProcessBuilder` Defaults