bb.util
Class OsUtil

java.lang.Object
  extended by bb.util.OsUtil

public final class OsUtil
extends Object

Provides static utility methods relating to the operating system that the JVM is running on.

This class is multithread safe: it is immutable (both its immediate state, as well as the deep state of its fields).

Author:
Brent Boyer

Nested Class Summary
private static class OsUtil.ExecTask
          Encapsulates all the work carried out by both the execSynch and execAsynch methods.
static class OsUtil.UnitTest
          See the Overview page of the project's javadocs for a general description of this unit test class.
 
Field Summary
private static String windows2000_osName
          Official name of the Microsoft Windows 2000 operating system.
private static String windows98_commandProcessor
          Name of the command processor program to execute DOS commands under Windows 98 (and below).
private static String windows98_osName
          Official name of the Microsoft Windows 98 operating system.
private static String windowsNt_commandProcessor
          Name of the command processor program to execute DOS commands under Windows NT (and above).
private static String windowsNt_osName
          Official name of the Microsoft Windows NT operating system.
private static String windowsXp_osName
          Official name of the Microsoft Windows XP operating system.
 
Constructor Summary
private OsUtil()
          This private constructor suppresses the default (public) constructor, ensuring non-instantiability.
 
Method Summary
static void execAsynch(String command)
          Simply calls execAsynch(command, null, null).
static void execAsynch(String command, String[] envp, File dir)
          Simply calls execAsynch(command, null, null, new StreamDrainerStoring(), new StreamDrainerStoring()).
static void execAsynch(String command, String[] envp, File dir, StreamDrainer outDrainer, StreamDrainer errDrainer)
          Executes a native (operating system specific) command in a new child process.
static byte[] execSynch(String command)
          Returns execSynch(command, null, null).
static byte[] execSynch(String command, String[] envp, File dir)
          Returns execSynch(command, null, null, new StreamDrainerStoring(), new StreamDrainerStoring()).
static byte[] execSynch(String command, String[] envp, File dir, StreamDrainer outDrainer, StreamDrainer errDrainer)
          Executes a native (operating system specific) command in a new child process.
private static boolean execSynchSucceeded(String command)
          Calls execSynch(command).
static String getCommandInvalid()
          Returns a known invalid command for the current operating system.
static String getCommandValid()
          Returns a known valid command for the current operating system.
static String getDosCommandProcessor()
          Returns the name of the command processor program used to execute DOS commands if this is a Microsoft operating system.
static String getOsName()
          Returns the current operating system name.
static String getOsNameAndVersion()
          Returns a concatenation (with a space char separator) of the current operating system name and version.
static String getOsVersion()
          Returns the current operating system version.
static boolean isMicrosoft()
          Determines whether or not the operating system is from Microsoft (e.g.
static boolean isUnix()
          Determines whether or not the operating system is Unix (including Linux and OS/X).
static boolean isWindows2000()
          Determines whether or not the operating system is Windows 2000 by comparing windows2000_osName to the result of getOsName.
static boolean isWindows98()
          Determines whether or not the operating system is Windows 98 by comparing windows98_osName to the result of getOsName.
static boolean isWindowsNT()
          Determines whether or not the operating system is Windows NT by comparing windowsNt_osName to the result of getOsName.
static boolean isWindowsXP()
          Determines whether or not the operating system is Windows 2000 by comparing windowsXp_osName to the result of getOsName.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

windows98_osName

private static final String windows98_osName
Official name of the Microsoft Windows 98 operating system.

See Also:
Constant Field Values

windowsNt_osName

private static final String windowsNt_osName
Official name of the Microsoft Windows NT operating system.

See Also:
Constant Field Values

windows2000_osName

private static final String windows2000_osName
Official name of the Microsoft Windows 2000 operating system.

See Also:
Constant Field Values

windowsXp_osName

private static final String windowsXp_osName
Official name of the Microsoft Windows XP operating system.

See Also:
Constant Field Values

windows98_commandProcessor

private static final String windows98_commandProcessor
Name of the command processor program to execute DOS commands under Windows 98 (and below).

See Also:
Constant Field Values

windowsNt_commandProcessor

private static final String windowsNt_commandProcessor
Name of the command processor program to execute DOS commands under Windows NT (and above).

See Also:
Constant Field Values
Constructor Detail

OsUtil

private OsUtil()
This private constructor suppresses the default (public) constructor, ensuring non-instantiability.

Method Detail

getCommandInvalid

public static String getCommandInvalid()
                                throws IllegalStateException
Returns a known invalid command for the current operating system. This method is used during testing.

Throws:
IllegalStateException - if unable to determine an invalid command for this operating system

getCommandValid

public static String getCommandValid()
                              throws IllegalStateException
Returns a known valid command for the current operating system. This method is used during testing.

Throws:
IllegalStateException - if unable to determine a valid command for this operating system

getDosCommandProcessor

public static String getDosCommandProcessor()
                                     throws IllegalStateException
Returns the name of the command processor program used to execute DOS commands if this is a Microsoft operating system.

Throws:
IllegalStateException - if unable to determine what DOS command processor to use for this operating system

getOsName

public static String getOsName()
Returns the current operating system name.


getOsVersion

public static String getOsVersion()
Returns the current operating system version.


getOsNameAndVersion

public static String getOsNameAndVersion()
Returns a concatenation (with a space char separator) of the current operating system name and version.


isMicrosoft

public static boolean isMicrosoft()
Determines whether or not the operating system is from Microsoft (e.g. DOS, Windows). All of these tests must be passed:
  1. File.separatorChar == '\\'
  2. getOsName contains the text "windows" or "msdos" (case irrelevant)
  3. the dos command ver was sucessfully executed


isWindows98

public static boolean isWindows98()
Determines whether or not the operating system is Windows 98 by comparing windows98_osName to the result of getOsName.


isWindowsNT

public static boolean isWindowsNT()
Determines whether or not the operating system is Windows NT by comparing windowsNt_osName to the result of getOsName.


isWindows2000

public static boolean isWindows2000()
Determines whether or not the operating system is Windows 2000 by comparing windows2000_osName to the result of getOsName.


isWindowsXP

public static boolean isWindowsXP()
Determines whether or not the operating system is Windows 2000 by comparing windowsXp_osName to the result of getOsName.


isUnix

public static boolean isUnix()
Determines whether or not the operating system is Unix (including Linux and OS/X). All of these tests must be passed:
  1. File.separatorChar == '/'
  2. the unix command uname was sucessfully executed


execSynchSucceeded

private static boolean execSynchSucceeded(String command)
Calls execSynch(command). Returns true if no Exception of any type was thrown, false otherwise. Used by this class to determine valid/invalid commands.


execSynch

public static byte[] execSynch(String command)
                        throws IllegalArgumentException,
                               RuntimeException
Returns execSynch(command, null, null). So, the process which executes command inherits the env vars and working directory of the current Java process.

Throws:
IllegalArgumentException
RuntimeException

execSynch

public static byte[] execSynch(String command,
                               String[] envp,
                               File dir)
                        throws IllegalArgumentException,
                               RuntimeException
Returns execSynch(command, null, null, new StreamDrainerStoring(), new StreamDrainerStoring()). In words:
  1. the process which executes command is synchronously executed
  2. that process uses the supplied env vars and working directory
  3. if that process terminates normally, then the bytes returned are all the bytes drained from its std out
  4. else if that process terminates abnormally, then the RuntimeException that is thrown will include all the bytes drained from both its std out and err

Warning: because StreamDrainerStoring instances handle the process's std streams, the command must not generate excessive output over its lifetime else the program may run out of memory.

Throws:
IllegalArgumentException
RuntimeException

execSynch

public static byte[] execSynch(String command,
                               String[] envp,
                               File dir,
                               StreamDrainer outDrainer,
                               StreamDrainer errDrainer)
                        throws IllegalArgumentException,
                               RuntimeException
Executes a native (operating system specific) command in a new child process. This method executes synchronously: it does not return until the command has finished (the child process terminates). See the execAsynch methods of this class for corresponding non-blocking versions.

The command must not require any input, since this method does not know how to supply it with any; the command will hang forever waiting for input if you mistakenly call this method with such a command. This will cause the calling thread to block indefinately.

The command may, however, produce arbitrary output on either stream (its std out or err streams). The outDrainer and errDrainer params will be initialized with the child process's std out and err streams respectively, and each will then be concurrently run in its own new thread. This guarantees that those streams are properly drained.

Parameters:
command - the operating system specific command to execute
envp - array of strings, each element of which has environment variable settings in the format name=value, or null if the subprocess should inherit the environment of the current process; see also Accessing the Environment from Java Applications
dir - the working directory of the subprocess, or null if the subprocess should inherit the working directory of the current process
outDrainer - used to drain the child process's std out stream; its init must not have been called
errDrainer - used to drain the child process's std err stream; its init must not have been called
Returns:
a byte[] containing everything written to the child process's std out stream assuming that outDrainer stored those bytes (see StreamDrainer for more discussion); if those bytes were not stored, then an empty (but never null) byte[] is returned
Throws:
IllegalArgumentException - if command is blank; envp is not null but has a blank element; dir is not null but is not valid; outDrainer is null; errDrainer is null
RuntimeException - if the native process terminates abnormally or wrote any data to its error stream, or if some other error was detected (will be stored in the cause field of this RuntimeException)

execAsynch

public static void execAsynch(String command)
                       throws IllegalArgumentException,
                              RuntimeException
Simply calls execAsynch(command, null, null). So, the process which executes command inherits the env vars and working directory of the current Java process.

Throws:
IllegalArgumentException
RuntimeException

execAsynch

public static void execAsynch(String command,
                              String[] envp,
                              File dir)
                       throws IllegalArgumentException,
                              RuntimeException
Simply calls execAsynch(command, null, null, new StreamDrainerStoring(), new StreamDrainerStoring()). In words:
  1. the process which executes command is asynchronously executed
  2. that process uses the supplied env vars and working directory
  3. that process's outcome is always logged to the default Logger when it terminates

Warning: because StreamDrainerStoring instances handle the process's std streams, the command must not generate excessive output over its lifetime else the program may run out of memory.

Throws:
IllegalArgumentException
RuntimeException

execAsynch

public static void execAsynch(String command,
                              String[] envp,
                              File dir,
                              StreamDrainer outDrainer,
                              StreamDrainer errDrainer)
                       throws IllegalArgumentException
Executes a native (operating system specific) command in a new child process. This method executes asynchronously: it simply establishes a background thread which handles the execution and then immediately returns. See the execSynch methods of this class for corresponding blocking versions.

The command must not require any input, since this method does not know how to supply it with any; the command will hang forever waiting for input if you mistakenly call this method with such a command. This will cause the background thread to block indefinately.

The command may, however, produce arbitrary output on either stream (its std out or err streams). The outDrainer and errDrainer params will be initialized with the child process's std out and err streams respectively, and each will then be concurrently run in its own new thread. This guarantees that those streams are properly drained.

The background thread ensures that process's outcome is always logged to the default Logger when it terminates.

Parameters:
command - the operating system specific command to execute
envp - array of strings, each element of which has environment variable settings in the format name=value, or null if the subprocess should inherit the environment of the current process; see also Accessing the Environment from Java Applications
dir - the working directory of the subprocess, or null if the subprocess should inherit the working directory of the current process
outDrainer - used to drain the child process's std out stream; its init must not have been called
errDrainer - used to drain the child process's std err stream; its init must not have been called
Throws:
IllegalArgumentException - if command is blank; envp is not null but has a blank element; dir is not null but is not valid; outDrainer is null; errDrainer is null