Class SystemUtils

java.lang.Object

org.tquadrat.foundation.util.SystemUtils

@ClassVersion(sourceVersion="$Id: SystemUtils.java 1182 2026-04-03 15:38:16Z tquadrat $")
@API(status=STABLE,
     since="0.0.5")
@UtilityClass
public final class SystemUtils
extends Object

This class provides some system related helper and convenience methods.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: SystemUtils.java 1182 2026-04-03 15:38:16Z tquadrat $

Since:

0.0.5

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.util.SystemUtils"

⁠

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	SystemUtils.OperatingSystem	The operating system families that are supported (or not) by Java. Currently, we can distinguish only between Microsoft Windows, UNIX/Linux and macOS/OS-X.

Field Summary

Fields

Modifier and Type	Field	Description
private static final BigInteger	m_NanoAdjust	The adjustment value that is used to align the time returned from System.nanoTime() with the system time.
private static Long	m_Node	The location or node id.
private static final long	m_NodeIdBits	The valid bits for a node id: 281474976710655L.
private static final long	m_NodeIdSign	The sign bit for a node id: 1099511627776L.
private static final Lazy<SystemUtils.OperatingSystem>	m_OperatingSystem	The operating system.
private static final Lazy<Pattern>	m_PatternIPv4Address	The pattern to check a string for an IPv4 address.
private static final Lazy<Random>	m_Random	The random number generator.
static final int	MAC_ADDRESS_Size	The length of a String containing a MAC address: 17.
private static final BigInteger	ONE_MILLION	Factor for the conversion of milliseconds to nanoseconds.
private static final BigInteger	ONE_THOUSAND	Factor for the conversion of seconds to milliseconds.
static final String	PATTERN_IPv4_ADDRESS	The regular expression for a valid IPv4 address: "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$".
static final String	PROPERTY_NODE_ID	The name of the system property for the node id: "org.tquadrat.foundation.util.SystemUtils.NodeId".

Constructor Summary

Constructors

Modifier	Constructor	Description
private	SystemUtils()	No instance allowed for this class.

Method Summary

Modifier and Type	Method	Description
static final InetAddress	convertIPAddress(CharSequence ipAddress)	Converts an IP address that is given as a string into an InetAddress object.
static final long	createPseudoNodeId()	Returns a pseudo node id; this is useful in cases a machine does not have a network card (NIC) so that a MAC address could not be obtained, or if the real node id should not be used.
static final Map<String,String>	createZoneIdAliasMap()	Deprecated, for removal: This API element is subject to removal in a future version. Use DateTimeUtils.createZoneIdAliasMap() instead.
static final BigInteger	currentTimeNanos()	Returns the current time as nanoseconds since the beginning of the Gregorian calendar (1582-10-15T00:00).
static final Optional<InetAddress>	determineIPAddress()	Determines an IP address of the machine this program is running on.
static final InetAddress[]	determineIPAddresses()	Determines all the IP addresses of the machine this program is running on.
private static final SystemUtils.OperatingSystem	determineOperatingSystem()	Determines the operating system.
static final InetAddress[]	determineOutboundIPAddresses()	Determines those IP addresses of the machine this program is running on that are used to communicate with the outside world.
static final String	formatNodeIdAsMAC(long nodeId)	Formats the given node id as a MAC address string.
static final String	getMACAddress()	Returns the MAC address for the current computer.
static final Collection<NetworkInterface>	getNetworkInterfaces()	Returns a Collection of all the network interfaces on this machine.
static final long	getNodeId()	Returns the unique id of this node.
static final SystemUtils.OperatingSystem	getOperatingSystem()	Returns the current operating system.
static final long	getPID()	Returns the PID, the process id, for the VM this (the current) program runs in.
static final Random	getRandom()	Returns the system random number generator.
static final String	getUserName()	Returns the current username from the system property "user.name".
static final Map<String,String>	getZoneIdAliasMap()	Deprecated, for removal: This API element is subject to removal in a future version. Use DateTimeUtils.getZoneIdAliasMap() instead.
static final boolean	hasNetworkInterface()	Checks whether the current system has a network interface installed.
static final boolean	repose(long millis)	An implementation of Thread.sleep(long) that does not throw an exception in case it will be interrupted.
static final boolean	repose(Duration duration)	An implementation of Thread.sleep(Duration) that does not throw an exception in case it will be interrupted.
static final boolean	reposeUntil(Instant until)	An implementation of sleepUntil(Instant) that does not throw an exception when interrupted.
static final Optional<Locale>	retrieveLocale(CharSequence localeName)	Retrieves an instance of Locale for the given locale name.
static final void	sleep(Duration duration)	Deprecated, for removal: This API element is subject to removal in a future version. Use Thread.sleep(Duration) instead.
static final void	sleepUntil(Instant until)	Causes the currently executing thread to sleep (temporarily cease execution) until the specified time, subject to the precision and accuracy of system timers and schedulers.
static final Map<String,String>	systemPropertiesAsStringMap()	Returns the system properties
static final long	translateMACToNodeId(String macAddress)	Translates a given MAC address into a numerical node id.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

m_NodeIdBits

@API(status=INTERNAL,
     since="0.1.0")
private static final long m_NodeIdBits

The valid bits for a node id: 281474976710655L.

See Also:

• m_Node
• Constant Field Values

m_NodeIdSign

@API(status=INTERNAL,
     since="0.1.0")
private static final long m_NodeIdSign

The sign bit for a node id: 1099511627776L.

See Also:

• m_Node
• Constant Field Values

MAC_ADDRESS_Size

@API(status=STABLE,
     since="0.0.5")
public static final int MAC_ADDRESS_Size

The length of a String containing a MAC address: 17.

See Also:

• Constant Field Values

ONE_MILLION

private static final BigInteger ONE_MILLION

Factor for the conversion of milliseconds to nanoseconds.

ONE_THOUSAND

private static final BigInteger ONE_THOUSAND

Factor for the conversion of seconds to milliseconds.

PATTERN_IPv4_ADDRESS

@API(status=STABLE,
     since="0.0.5")
public static final String PATTERN_IPv4_ADDRESS

The regular expression for a valid IPv4 address: "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$".

See Also:

• Constant Field Values

PROPERTY_NODE_ID

@API(status=STABLE,
     since="0.1.0")
public static final String PROPERTY_NODE_ID

The name of the system property for the node id: "org.tquadrat.foundation.util.SystemUtils.NodeId".

The value has to be a positive number. It will be parsed by Long.decode(String); this means, it could be a decimal, a hex or an octal number – so be careful with leading zeroes!

This system property is not necessarily configured; if missing, the node id will be determined by the hardware address of the NIC.

See Also:

• getNodeId()
• Constant Field Values

m_Node

private static Long m_Node

The location or node id.

m_NanoAdjust

private static final BigInteger m_NanoAdjust

The adjustment value that is used to align the time returned from System.nanoTime() with the system time.

See Also:

• currentTimeNanos()

m_OperatingSystem

private static final Lazy<SystemUtils.OperatingSystem> m_OperatingSystem

The operating system.

m_PatternIPv4Address

private static final Lazy<Pattern> m_PatternIPv4Address

The pattern to check a string for an IPv4 address.

m_Random

private static final Lazy<Random> m_Random

The random number generator.

Constructor Details

SystemUtils

private SystemUtils()

No instance allowed for this class.

Method Details

convertIPAddress

@API(status=EXPERIMENTAL,
     since="0.0.5")
public static final InetAddress convertIPAddress(CharSequence ipAddress)

Converts an IP address that is given as a string into an InetAddress object.

TODO Currently this method do not process IPv6 addresses properly.

Parameters:

ipAddress - The string with the IP address.

Returns:

The InetAddress object.

Throws:

IllegalArgumentException - The given parameter is not a valid IP address.

createPseudoNodeId

@API(status=STABLE,
     since="0.0.5")
public static final long createPseudoNodeId()

Returns a pseudo node id; this is useful in cases a machine does not have a network card (NIC) so that a MAC address could not be obtained, or if the real node id should not be used.

Each call to this method will return a new value.

Returns:

The node id.

createZoneIdAliasMap

@API(status=DEPRECATED,
     since="0.0.6")
@Deprecated(since="0.4.0",
            forRemoval=true)
public static final Map<String,String> createZoneIdAliasMap()

Deprecated, for removal: This API element is subject to removal in a future version.

Use DateTimeUtils.createZoneIdAliasMap() instead.

Creates the alias map for the old (deprecated) zone ids that are used for the call to ZoneId.of(String, java.util.Map) to retrieve a ZoneId instance for the given zone id.

Returns:

The alias map.

Since:

0.0.6

currentTimeNanos

@API(status=STABLE,
     since="0.0.5")
public static final BigInteger currentTimeNanos()

Returns the current time as nanoseconds since the beginning of the Gregorian calendar (1582-10-15T00:00).

Returns:

The current time in nanoseconds.

determineIPAddress

@API(status=STABLE,
     since="0.0.5")
public static final Optional<InetAddress> determineIPAddress()
                                                      throws SocketException

Determines an IP address of the machine this program is running on. Usually this will be one of the addresses that is visible to the outside. In addition, the method has a clear precedence for IPv4 addresses over IPv6 ones.

Returns:

An instance of Optional that holds the IP address; it will be empty if really no network adapter is active on this machine.

Throws:

SocketException - Problems to retrieve the internet address.

determineIPAddresses

@API(status=STABLE,
     since="0.0.5")
public static final InetAddress[] determineIPAddresses()

Determines all the IP addresses of the machine this program is running on.

Returns:

The IP addresses.

determineOperatingSystem

private static final SystemUtils.OperatingSystem determineOperatingSystem()

Determines the operating system.

Returns:

The operating system.

determineOutboundIPAddresses

@API(status=STABLE,
     since="0.0.5")
public static final InetAddress[] determineOutboundIPAddresses()

Determines those IP addresses of the machine this program is running on that are used to communicate with the outside world. This means that only those active network interfaces are considered that are not a loopback interface.

Returns:

The IP addresses.

formatNodeIdAsMAC

@API(status=STABLE,
     since="0.0.5")
public static final String formatNodeIdAsMAC(long nodeId)

Formats the given node id as a MAC address string.

Parameters:

nodeId - The node id.

Returns:

The MAC address string.

getMACAddress

@API(status=STABLE,
     since="0.0.5")
public static final String getMACAddress()

Returns the MAC address for the current computer. In case the machine will have more than one network card (NIC), the returned MAC is selected in the same as for getNodeId().

Returns:

The MAC address.

getNetworkInterfaces

@API(status=STABLE,
     since="0.0.5")
public static final Collection<NetworkInterface> getNetworkInterfaces()

Returns a Collection of all the network interfaces on this machine. Instead of throwing an exception, the method will return an empty collection in case the machine do not have network configured. Otherwise, the collection contains at least one element, possibly representing a loopback interface that only supports communication between entities on this machine.

Returns:

The NetworkInterfaces found on this machine.

See Also:

• NetworkInterface.getNetworkInterfaces()

getNodeId

@API(status=STABLE,
     since="0.0.5")
public static final long getNodeId()

Returns the unique id of this node.

Returns:

The node id.

See Also:

• PROPERTY_NODE_ID

getOperatingSystem

@API(status=STABLE,
     since="0.0.6")
public static final SystemUtils.OperatingSystem getOperatingSystem()

Returns the current operating system.

Returns:

The operating system.

getPID

@API(status=STABLE,
     since="0.0.5")
public static final long getPID()
                         throws UnsupportedOperationException

Returns the PID, the process id, for the VM this (the current) program runs in.

Returns:

The PID.

Throws:

UnsupportedOperationException - The implementation of ProcessHandle that is currently in use does not support the operation ProcessHandle.pid().

See Also:

• ProcessHandle.pid()

getRandom

@API(status=STABLE,
     since="0.0.5")
public static final Random getRandom()

Returns the system random number generator.

Returns:

The random number generator.

getUserName

@API(status=STABLE,
     since="0.4.8")
public static final String getUserName()

Returns the current username from the system property "user.name".

Returns:

The username.

Since:

0.4.8

getZoneIdAliasMap

@API(status=DEPRECATED,
     since="0.0.5")
@Deprecated(since="0.4.0",
            forRemoval=true)
public static final Map<String,String> getZoneIdAliasMap()

Deprecated, for removal: This API element is subject to removal in a future version.

Use DateTimeUtils.getZoneIdAliasMap() instead.

Returns the alias map; if not yet created, the alias map will be created by a call to createZoneIdAliasMap() and the result to that call will be cached for future calls.

Returns:

The alias map.

Since:

0.0.6

See Also:

• createZoneIdAliasMap()

hasNetworkInterface

@API(status=STABLE,
     since="0.0.5")
public static final boolean hasNetworkInterface()

Checks whether the current system has a network interface installed.

Returns:

true if the current system has a network interface installed, false otherwise.

repose

@API(status=STABLE,
     since="0.0.7")
public static final boolean repose(long millis)

An implementation of Thread.sleep(long) that does not throw an exception in case it will be interrupted.

Note:

• While sleeping, the thread does not lose ownership of any monitors.

Parameters:

millis - The time to sleep in milliseconds.

Returns:

true if the sleep was interrupted, false if it terminated as planned.

repose

@API(status=STABLE,
     since="0.0.7")
public static final boolean repose(Duration duration)

An implementation of Thread.sleep(Duration) that does not throw an exception in case it will be interrupted.

Note:

• While sleeping, the thread does not lose ownership of any monitors.

Parameters:

duration - The time to sleep.

Returns:

true if the sleep was interrupted, false if it terminated as planned.

reposeUntil

@API(status=STABLE,
     since="0.0.7")
public static final boolean reposeUntil(Instant until)

An implementation of sleepUntil(Instant) that does not throw an exception when interrupted.

Note:

• While sleeping, the thread does not lose ownership of any monitors.

Parameters:

until - The end time for the sleep period.

Returns:

true if the sleep was interrupted, false if it terminated as planned.

retrieveLocale

@API(status=STABLE,
     since="0.0.6")
public static final Optional<Locale> retrieveLocale(CharSequence localeName)

Retrieves an instance of Locale for the given locale name. This method will look up the requested locale first in the locales returned by Locale.getAvailableLocales() before it will create a new instance of Locale using Locale.Builder.

The method will return Optional.empty() when the format of the given localeName is invalid.

If none of the already existing instances of Locale matches the given name, the language part, the country part, the variant part and the script part (if provided) are used to create a new instance. If extensions are given, they will be ignored.

If the given locale name is empty or contains only whitespace, the method will return Locale.ROOT.

Parameters:

localeName - The name of the locale.

Returns:

An instance of Optional that holds the instance of Locale for the given name.

sleep

@API(status=DEPRECATED,
     since="0.0.7")
@Deprecated(since="0.4.8",
            forRemoval=true)
public static final void sleep(Duration duration)
                        throws InterruptedException

Deprecated, for removal: This API element is subject to removal in a future version.

Use Thread.sleep(Duration) instead.

An implementation of Thread.sleep(long) that takes an instance of Duration to determine the time to sleep.

Note:

• While sleeping, the thread does not lose ownership of any monitors.

Parameters:

duration - The time to sleep.

Throws:

InterruptedException - Another thread has interrupted the current thread (that one executing sleep()). The interrupted status of the current thread is cleared when this exception is thrown.

sleepUntil

@API(status=STABLE,
     since="0.0.7")
public static final void sleepUntil(Instant until)
                             throws InterruptedException

Causes the currently executing thread to sleep (temporarily cease execution) until the specified time, subject to the precision and accuracy of system timers and schedulers. The thread does not lose ownership of any monitors.

Note:

• While sleeping, the thread does not lose ownership of any monitors.

Parameters:

until - The end time for the sleep.

Throws:

InterruptedException - Another thread has interrupted the current thread (that one executing sleep()). The interrupted status of the current thread is cleared when this exception is thrown.

Since:

0.0.7

See Also:

• Thread.sleep(long)

systemPropertiesAsStringMap

public static final Map<String,String> systemPropertiesAsStringMap()

Returns the system properties as a Map<String,String>.

System.getProperties() returns an instance of Properties, and that is implementing Map<String,Object>. Although it is unlikely that a value is not a String (if not impossible …), this method allows to enforce it.

Note:

• A mere cast to Map<String,String> does not work …

Returns:

An unmodifiable map with the system properties as Strings.

translateMACToNodeId

@API(status=STABLE,
     since="0.0.5")
public static final long translateMACToNodeId(String macAddress)

Translates a given MAC address into a numerical node id.

A MAC address is a string consisting of 12 hex digits, grouped by two, each group separated by a hyphen: xx-xx-xx-xx-xx-xx

Parameters:

macAddress - The MAC address to translate.

Returns:

The node id.