single instance : Java Glossary


single instance

You may want to prevent the user from spawning multiple copies of your Java application. The Java community would be grateful to anyone who solves this and packages it up as a black box that works on all major platforms and does not require special configuration. I have submitted

Oracle RFE number 2416600 : single instance support in applications

Here are seven approaches:

  1. Test for the presence of a busy.marker file. If one exists, abort. If not create one. The test and create can be in the bat file that triggers the app or in the app itself. When the app exists it deletes the busy.marker marker file. The main problem with this simple approach is if your app crashes, it won’t delete the busy.marker file. You have to manually delete it before you can run the app again.
  2. Another approach is to have your application open a ServerSocket on a particular port number. The OS (Operating System) will prevent other processes from opening a ServerSocket that uses the same port. If you start the application and are unable to open your ServerSocket (i.e. if you get an address already in use exception) assume that the application is already running. In that case, you can use a Socket to connect to the running application and pass it whatever commands you like, or just abort. The problem with this is you must assign a port number that no other program is using. There is no way to do that other than trial an error — a nasty complication for your users. details alternate.
  3. Some platform specific native code invoked via JNI (Java Native Interface). E.g. use an OS Mutex on Windows.
  4. Use file locking. You lock a file after testing to see if it is locked. The catch is, a crash may not free the lock. A reboot should always clear it, which is simpler than asking the user to delete a file. details.
  5. You might be able to avoid the need of dealing with a magic file or hard-coded socket port by using UDP (User Datagram Protocol) multicast with the SO_REUSEADDR option. This would allow your program to join to a multicast port without interference from other programs, ensuring it’s ready to receive a UDP datagram sent on the channel from a new instance searching for a prior existing instance.
  6. A common approach for Unix and descendants is to use a file with a known absolute pathname that contains the process PID (Process Identifier). The clever trick is that the program that creates the file immediately closes and reopens it for reading and then deletes the file without closing it: this works because file deletion is deferred until there are no longer any processes that have the file open. When a process dies or is killed, all the files it had open are closed. If the file exists and has a different pid to the checker, then another copy is running. There is no clean-up needed: if the user kills the program the file vanishes because it only remains in existence as long as at least one process has the file open.

  7. A common approach is to use an indicator file, which contains the PID of the main process. That way you can check if that PID is still active. This, of course, isn’t platform independent. You could combine the idea with others above though. Check the file, which contains a TCP (Transmission Control Protocol) port number, connect to that port number to check if the process is still alive.
  8. You could use a database, which has ways of synchronising.
  9. For some apps you don’t want the latecomer to just die, but to send a message to running instance, passing it the command line parameters to process.

Learning More

Oracle’s Javadoc on FileLock class : available:
Oracle’s Javadoc on DatagramPacket class : available:
Oracle’s Javadoc on MulticastSocket class : available:

This page is posted
on the web at:

Optional Replicator mirror
on local hard disk J:

Canadian Mind Products
Please the feedback from other visitors, or your own feedback about the site.
Contact Roedy. Please feel free to link to this page without explicit permission.

Your face IP:[]
You are visitor number