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

To use this approach, configure the PreparedStatement as follows:

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:

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

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

The advantages of zt-exec are as follows.

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

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.

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 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.