org.safs.natives

Class NativeWrapper

java.lang.Object

org.safs.natives.NativeWrapper

Direct Known Subclasses:

MenuUtilities

public class NativeWrapper
extends java.lang.Object

This class is used to encapsulate platform independent calls to native operating systems through JNA, or other native platform technologies.

JNA is the Java Native Access library supplied via JNA Home

JNA provides Java programs easy access to native shared libraries on multiple operating systems without writing anything but Java code JNI or native code is required. This functionality is comparable to Windows' Platform/Invoke and Python's ctypes. Access is dynamic at runtime without code generation.

SAFS is now delivered with the core JNA.ZIP(JAR). Other JNA support libraries may be added as needed.

Since:

2009.02.03

Author:

Carl Nagle

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ARG_FILE_FOR_GETTIME "-fileforgettime" followed by a full path file name, for testing getFileTime(String, Date, Date, Date)
static java.lang.String	ARG_HOSTNAME "-hostname" followed by a hostname, for testing getHostIPByPing(String)
static java.lang.String	COMMAND_HOSTNMAE command 'hostname'
static java.lang.String	COMMAND_IFCONFIG command 'ifconfig'
static java.lang.String	COMMAND_IPCONFIG command 'ipconfig'
static java.lang.String	COMMAND_PING command 'ping'
static java.lang.String	DIRECTORY_SBIN directory 'sbin'
static int	NO_RESULT -99
static java.lang.String	PARAM_HOSTNMAE_f parameter '-f' for command 'hostname', to get full qualified domain name
static java.lang.String	REG_BINARY
static java.lang.String	REG_DWORD
static java.lang.String	REG_EXPAND_SZ
static java.lang.String	REG_MULTI_SZ
static java.lang.String	REG_NONE
static java.lang.String	REG_QWORD
static java.lang.String	REG_SZ
static java.lang.String	RESULT_KEY "Result"
static java.lang.String	VECTOR_KEY "Vector"

Constructor Summary

Constructors

Constructor and Description
NativeWrapper()

Method Summary

Modifier and Type	Method and Description
protected static int	_processLastError() Retrieves last error via GetLastError and also attempts to debug log the error code and any system message for the error code.
static boolean	DoesRegistryKeyExist(java.lang.Object key, java.lang.Object valuename) True if the requested "registry key" already exists, false otherwise. This is currently only supported on Windows.
static java.lang.Object[]	EnumChildWindows(java.lang.Object parent) Platform independent entry-point to receive the ID or HANDLE of all child Windows of a parent.
static java.lang.Object[]	EnumWindows() Platform independent entry-point to receive the ID or HANDLE of all top-level Windows.
static java.util.List<java.lang.String>	execute(java.lang.String command, java.lang.String... parameters) Return the result of execution of a command as a List of String. Note: The command MUST end with limit result, otherwise this method will block.
static java.lang.Object	GetDesktopWindow() Platform independent entry-point to receive the ID or HANDLE of the Desktop window.
static boolean	getFileTime(java.lang.String filename, java.util.Date createTime, java.util.Date accessTime, java.util.Date writeTime) This method will get the file's created time, access time, and write time.
static java.lang.Object	GetForegroundWindow() Platform independent entry-point to receive the ID or HANDLE of the current foreground window.
static java.lang.String	getHostIPByPing(java.lang.String hostname) Get the host's IP Address by command COMMAND_PING.
static java.lang.String	getLocalHostIPByConfig() Execute COMMAND_IPCONFIG or COMMAND_IFCONFIG to parse the local IP address.
static java.lang.String	getLocalHostName()
static java.lang.Object	GetProcessFileName(java.lang.Object processID) Retrieve the name of the executable file for the specified process.
static java.lang.Object	GetProcessUIResourceCount(java.lang.Object processID) Retrieve the count of UI elements used by the specified process.
static java.lang.Object	GetRegistryKeyValue(java.lang.Object key, java.lang.Object valuename) Return the value of the specified key.
static java.lang.String	GetSystemEnvironmentVariable(java.lang.Object key) Get a System Environment Variable.
static java.lang.Object[]	GetWindowThreadProcessId(java.lang.Object parent) The GetWindowThreadProcessId function retrieves the identifier of the thread that created the specified window and, optionally, the identifier of the process that created the window.
static java.util.List<java.lang.String>	ifconfig(java.lang.String... parameters) Return the ifconfig's result as a List of String.
static java.util.List<java.lang.String>	ipconfig(java.lang.String... parameters) Return the ipconfig's result as a List of String.
static java.lang.Object	LaunchURLInDefaultWebBrowser(java.lang.String url) Attempt to launch a web URL via the system's default web browser.
static void	main(java.lang.String[] args) Test some implementations of this class. Simple regression tests with output to System.out
static java.util.List<java.lang.String>	ping(java.lang.String hostname, java.lang.String... parameters) Return the ping's result as a List of String.
static boolean	RemoveRegistryKeyValue(java.lang.Object key, java.lang.Object valuename) Remove a registry key, and/or key value.
static boolean	RemoveSystemEnvironmentVariable(java.lang.Object key) Delete/Remove a System Environment Variable.
static boolean	runAsynchBatchProcess(java.lang.String workdir, java.lang.String... batchAndargs) Runs an asynch batch process and immediately returns.
static boolean	runAsynchExec(java.lang.String fullpath) Runs an asynch exec and immediately returns.
static java.util.Hashtable	runShortProcessAndWait(java.lang.String proc, java.lang.String... args) Runs a short process and waits for it to complete.
static boolean	SetForegroundWindow(java.lang.String regex_title) Set ForeGroundWindow active by title.
static boolean	SetRegistryKeyValue(java.lang.Object key, java.lang.Object valuename, java.lang.String strtype, java.lang.Object... vals) Set/Create a registry key, and/or key value.
static boolean	SetSystemEnvironmentVariable(java.lang.Object key, java.lang.Object value) Set/Create a System Environment Variable.

Methods inherited from class java.lang.Object

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

Field Detail

NO_RESULT

public static final int NO_RESULT

-99

See Also:

Constant Field Values

VECTOR_KEY

public static final java.lang.String VECTOR_KEY

"Vector"

See Also:

Constant Field Values

RESULT_KEY

public static final java.lang.String RESULT_KEY

"Result"

See Also:

Constant Field Values

REG_SZ

public static final java.lang.String REG_SZ

See Also:

Constant Field Values

REG_EXPAND_SZ

public static final java.lang.String REG_EXPAND_SZ

See Also:

Constant Field Values

REG_MULTI_SZ

public static final java.lang.String REG_MULTI_SZ

See Also:

Constant Field Values

REG_DWORD

public static final java.lang.String REG_DWORD

See Also:

Constant Field Values

REG_QWORD

public static final java.lang.String REG_QWORD

See Also:

Constant Field Values

REG_BINARY

public static final java.lang.String REG_BINARY

See Also:

Constant Field Values

REG_NONE

public static final java.lang.String REG_NONE

See Also:

Constant Field Values

COMMAND_PING

public static final java.lang.String COMMAND_PING

command 'ping'

See Also:

Constant Field Values

COMMAND_IPCONFIG

public static final java.lang.String COMMAND_IPCONFIG

command 'ipconfig'

See Also:

Constant Field Values

COMMAND_IFCONFIG

public static final java.lang.String COMMAND_IFCONFIG

command 'ifconfig'

See Also:

Constant Field Values

COMMAND_HOSTNMAE

public static final java.lang.String COMMAND_HOSTNMAE

command 'hostname'

See Also:

Constant Field Values

PARAM_HOSTNMAE_f

public static final java.lang.String PARAM_HOSTNMAE_f

parameter '-f' for command 'hostname', to get full qualified domain name

See Also:

Constant Field Values

DIRECTORY_SBIN

public static final java.lang.String DIRECTORY_SBIN

directory 'sbin'

See Also:

Constant Field Values

ARG_FILE_FOR_GETTIME

public static final java.lang.String ARG_FILE_FOR_GETTIME

"-fileforgettime" followed by a full path file name, for testing getFileTime(String, Date, Date, Date)

See Also:

Constant Field Values

ARG_HOSTNAME

public static final java.lang.String ARG_HOSTNAME

"-hostname" followed by a hostname, for testing getHostIPByPing(String)

See Also:

Constant Field Values

Constructor Detail

NativeWrapper

public NativeWrapper()

Method Detail

DoesRegistryKeyExist

public static boolean DoesRegistryKeyExist(java.lang.Object key,
                                           java.lang.Object valuename)

True if the requested "registry key" already exists, false otherwise.
This is currently only supported on Windows.

The Windows version uses Reg.EXE which is supplied with WindowsXP. If this EXE is not present on the Windows system then this function will return false.

Parameters:

key - For Windows this is a String. Ex:"HKLM\Software\Rational Software\Rational Test\8\Options"

valuename - For Windows this is a String. Ex:"SpyHeapSize"

Returns:

true if the key and value exists, false if it does not.

runShortProcessAndWait

public static java.util.Hashtable runShortProcessAndWait(java.lang.String proc,
                                                         java.lang.String... args)
                                                  throws java.io.IOException

Runs a short process and waits for it to complete. Provides a Hashtable that will contain the exit code and system out and err data:

"Result" key returns and Integer Object containing the value of the exit code.
"Vector" key contains a jav.util.Vector object of the console output Strings from the process.

System.out console output lines are prefixed with "OUT: "
System.err console output lines are prefixed with "ERR: "

Parameters:

proc - Ex: "myProg" -- the caller must do any necessary quoting if the proc path contains spaces that would interfere with finding and executing the process.

args - Ex: "-u" or String[]{"-u", "arg2", "arg3"}. The caller must do any necessary quoting of individual arguments if spaces in the arguments will interfere with proper interpretation of the arguments by the process.

Returns:

Hashtable containing process output "Vector" as a Vector and "Result" as an Integer. The value of the Integer will be dependent on what the process returns, if anything. The Integer will contain NO_RESULT (-99) if the program was not successfully processed. The Vector may be empty if no data was received from the process.

Throws:

java.io.IOException - if the process was not executed on the system.

runAsynchBatchProcess

public static boolean runAsynchBatchProcess(java.lang.String workdir,
                                            java.lang.String... batchAndargs)
                                     throws java.io.IOException

Runs an asynch batch process and immediately returns.

Parameters:

workdir - The fullpath to a valid directory to be used as the batch working directory.
Ex: "C:\\STAF"

batchAndargs - the program and arguments array. The first item in the array is the batch program to execute.

Returns:

true if successfully launched

Throws:

java.io.IOException - if the process path was not valid or was not executed on the system.

See Also:

Console

runAsynchExec

public static boolean runAsynchExec(java.lang.String fullpath)
                             throws java.io.IOException

Runs an asynch exec and immediately returns.

Parameters:

Full - path of the file.

Returns:

true if successfully launched

Throws:

java.io.IOException - if the process path was not valid or was not executed on the system.

SetRegistryKeyValue

public static boolean SetRegistryKeyValue(java.lang.Object key,
                                          java.lang.Object valuename,
                                          java.lang.String strtype,
                                          java.lang.Object... vals)

Set/Create a registry key, and/or key value. This is currently only supported on Windows.

The Windows version uses Reg.EXE which is supplied with WindowsXP. If this EXE is not present on the Windows system then this function will always return false.

Parameters:

strkey - Ex:"HKLM\Software\Rational Software\Rational Test\8\Options"

strname - (Optional) Ex: The Name of a value to put under the key.

strtype - (Optional) Ex: REG_SZ or REG_MULTI_SZ, etc. (REG_SZ is the default)

strval[] - (Optional) One or more values to place in the strname value. Multiple values should only be used for REG_MULTI_SZ types.

Returns:

true if the operation completed successfully. false otherwise.

RemoveRegistryKeyValue

public static boolean RemoveRegistryKeyValue(java.lang.Object key,
                                             java.lang.Object valuename)

Remove a registry key, and/or key value. This is currently only supported on Windows.

The Windows version uses Reg.EXE which is supplied with WindowsXP. If this EXE is not present on the Windows system then this function will always return false.

Parameters:

strkey - Ex:"HKLM\Software\Rational Software\Rational Test\8\Options"

strname - (Optional) Ex: The Name of a value to put under the key.

Returns:

true if the operation completed successfully. false otherwise.

SetSystemEnvironmentVariable

public static boolean SetSystemEnvironmentVariable(java.lang.Object key,
                                                   java.lang.Object value)

Set/Create a System Environment Variable. This is currently only supported on Windows.

The Windows version uses SetX.EXE Vista and later. If this EXE is not present on the Windows system then will try to set the value through the Registry.

Because the system combines LOCAL variables and USER variables on any get, when we go to SET we do NOT want to have USER variable values mixed in. They will be duplicated if they are mixed in. So, on any SET, we must try to make sure we remove USER variables from the value we are setting.

Parameters:

strkey - Ex:"MY_VAR_NAME"

strval - Ex:"My variable value."

Returns:

true if the operation completed successfully. false otherwise.

RemoveSystemEnvironmentVariable

public static boolean RemoveSystemEnvironmentVariable(java.lang.Object key)

Delete/Remove a System Environment Variable. This is currently only supported on Windows.

The Windows version uses REG.EXE Vista and later. If this EXE is not present on the Windows system then we will exit with failure.

Parameters:

strkey - Ex:"SAFSDIR"

Returns:

true if the operation completed successfully. false otherwise.

GetSystemEnvironmentVariable

public static java.lang.String GetSystemEnvironmentVariable(java.lang.Object key)

Get a System Environment Variable. This is currently only supported on Windows.

The Windows version uses ECHO.

Note: variables set or changed after JVM start are NOT available to the currently running JVM through System.getEnv(). This is because the JVM does not refresh its Environment variable space after launch. Use GetSystemEnvironmentVariable to get the latest "refreshed" value of any System Environment Variable.

Parameters:

strkey - Ex:"MY_VAR_NAME"

Returns:

String value of the variable, or null if it does not exist.

GetRegistryKeyValue

public static java.lang.Object GetRegistryKeyValue(java.lang.Object key,
                                                   java.lang.Object valuename)

Return the value of the specified key. Null if the value does not exist.
This is currently only supported on Windows.

The Windows version uses Reg.EXE which is supplied with WindowsXP. If this EXE is not present on the Windows system then this function will always return false.

Parameters:

key - For Windows this is a String. Ex:"HKLM\Software\Rational Software\Rational Test\8\Options"

valuename - For Windows this is a String. Ex:"SpyHeapSize"

Returns:

Windows returns a String or null. Ex:"0x00200000". An empty string may be possible if no values are retrieved for a valid key. If valuename is null, then all the key values will be returned bracketed in the format: [key=val][key2=val2][key3=val3] etc...

_processLastError

protected static int _processLastError()

Retrieves last error via GetLastError and also attempts to debug log the error code and any system message for the error code.

Returns:

last error code encountered or 0

GetForegroundWindow

public static java.lang.Object GetForegroundWindow()

Platform independent entry-point to receive the ID or HANDLE of the current foreground window. The GetForegroundWindow function returns a "handle" to the foreground window--the window with which the user is currently working.

For windows NOTE: WIN32: we will return a Long representing the Handle (HWND), or null on error. NOTE: Support for other Platforms will be added as needed.

Returns:

See Also:

User32.GetForegroundWindow()

SetForegroundWindow

public static boolean SetForegroundWindow(java.lang.String regex_title)

Set ForeGroundWindow active by title. If there are same title match then first window make active. Regular expression is allowed for windows title.

Parameters:

title - - Title of the window; Regular expression allowed.

Returns:

boolean

See Also:

User32.ShowWindow(NativeLong, int)

GetDesktopWindow

public static java.lang.Object GetDesktopWindow()

Platform independent entry-point to receive the ID or HANDLE of the Desktop window. The GetDesktopWindow function returns a "handle" to the window on which all other windows are painted.

For windows NOTE: WIN32: we will return a Long representing the Handle (HWND), or null on error. NOTE: Support for other Platforms will be added as needed.

Returns:

See Also:

User32.GetDesktopWindow()

EnumWindows

public static java.lang.Object[] EnumWindows()

Platform independent entry-point to receive the ID or HANDLE of all top-level Windows. The EnumWindows function returns an array of "handles" to these top-level windows.

For windows NOTE: WIN32: we will return an array of Longs representing the Handles (HWND), or null on error. NOTE: Support for other Platforms will be added as needed.

Returns:

Object[] of Longs or Object[0].

See Also:

User32.EnumWindows(WNDENUMPROC,Pointer)

EnumChildWindows

public static java.lang.Object[] EnumChildWindows(java.lang.Object parent)

Platform independent entry-point to receive the ID or HANDLE of all child Windows of a parent. The EnumChildWindows function returns an array of "handles" to these child windows.

For windows NOTE: WIN32: we will return an array of Longs representing the Handles (HWND), or null on error. NOTE: Support for other Platforms will be added as needed.

Parameters:

handle - to the parent. For WIN32, this is a Long.

Returns:

Object[] of Longs or Object[0].

See Also:

User32.EnumWindows(WNDENUMPROC,Pointer)

GetWindowThreadProcessId

public static java.lang.Object[] GetWindowThreadProcessId(java.lang.Object parent)

The GetWindowThreadProcessId function retrieves the identifier of the thread that created the specified window and, optionally, the identifier of the process that created the window.

Parameters:

parent - - handle to the parent. For WIN32, this is a Long.

Returns:

Object[2] [0]=ThreadID, [1]=ProcessID. For WIN32 these are both Integers. Array values must be <> 0 to be considered valid.

GetProcessUIResourceCount

public static java.lang.Object GetProcessUIResourceCount(java.lang.Object processID)

Retrieve the count of UI elements used by the specified process. If the process does not have any UI elements, then we should get zero. NOTE: Support for non-WIN32 platforms will be added when able. NOTE: Will not work on "protected processes" on Windows Vista.

Parameters:

processID - -- the id of the process to query. For WIN32 this is an Integer.

Returns:

Object -- the number of UI elements used by the process, or 0. For WIN32 this is an Integer.

See Also:

org.safs.natives.win32.Kernel32#GetGuiResources(Pointer, int)

GetProcessFileName

public static java.lang.Object GetProcessFileName(java.lang.Object processID)

Retrieve the name of the executable file for the specified process. The returned value should not include path information to the executable filename. NOTE: Support for non-WIN32 platforms will be added when able.

Parameters:

processID - -- the id of the process to query. For WIN32 this is an Integer.

Returns:

Object -- the name of the process or NULL. For WIN32 this is a String.

See Also:

Kernel32.GetProcessImageFileNameA(Pointer, Pointer, int), Psapi.GetProcessImageFileNameA(Pointer, Pointer, int)

LaunchURLInDefaultWebBrowser

public static java.lang.Object LaunchURLInDefaultWebBrowser(java.lang.String url)

Attempt to launch a web URL via the system's default web browser.

On Windows this uses ShellExecute's "open" operation to open the URL document using the default app.

Parameters:

url - -- User should include the 'protocol' portion of the url (Ex: 'http://')

Returns:

Object -- For WIN32 this is typically an Integer(42). NULL on execution failures.

See Also:

Shell32.ShellExecuteA(NativeLong, String, String, String, String, long)

getFileTime

public static boolean getFileTime(java.lang.String filename,
                                  java.util.Date createTime,
                                  java.util.Date accessTime,
                                  java.util.Date writeTime)

 This method will get the file's created time, access time, and write time.
 Dor in parameter filename: it MUST be an absolute file path.
 For out parameters: createTime, accessTime and writeTime, if you don't want
 some of them, you can just pass a null value; If you want some of them, you
 MUST pass an instance of java.util.Date as value.
 

Parameters:

filename - In The absolute file path

createTime - Out The java.util.Date object contains the file created time

accessTime - Out The java.util.Date object contains the file last accessed time

writeTime - Out The java.util.Date object contains the file last modified time

Returns:

A boolean to indicate if this method get the file time successfully

ipconfig

public static java.util.List<java.lang.String> ipconfig(java.lang.String... parameters)

Return the ipconfig's result as a List of String. This is for Windows.

Parameters:

parameters - String[], the parameters for command ping.

Returns:

List a list containing the result of execution of command 'ipconfig'

ifconfig

public static java.util.List<java.lang.String> ifconfig(java.lang.String... parameters)

Return the ifconfig's result as a List of String. This is for Mac or Unix/Linux.

Parameters:

parameters - String[], the parameters for command ping.

Returns:

List a list containing the result of execution of command 'ifconfig'

ping

public static java.util.List<java.lang.String> ping(java.lang.String hostname,
                                                    java.lang.String... parameters)

Return the ping's result as a List of String.

Parameters:

hostname - String, the name of the host to ping

parameters - String[], the parameters for command ping.

Returns:

List a list containing the result of execution of command 'ping'

execute

public static java.util.List<java.lang.String> execute(java.lang.String command,
                                                       java.lang.String... parameters)

Return the result of execution of a command as a List of String.
Note: The command MUST end with limit result, otherwise this method will block.

Parameters:

parameters - String[], the parameters for command.

Returns:

List a list containing the result of execution of command

getHostIPByPing

public static java.lang.String getHostIPByPing(java.lang.String hostname)

Get the host's IP Address by command COMMAND_PING.

See Also:

#getHostIPByName(String)

getLocalHostIPByConfig

public static java.lang.String getLocalHostIPByConfig()

Execute COMMAND_IPCONFIG or COMMAND_IFCONFIG to parse the local IP address.

Returns:

String, IP address of localhost.

getLocalHostName

public static java.lang.String getLocalHostName()

Returns:

String, hostname of localhost

main

public static void main(java.lang.String[] args)

Test some implementations of this class.
Simple regression tests with output to System.out

java org.safs.natives.NativeWrapper > outputFile.txt

To test getFileTime(String, Date, Date, Date), call as following:
java java org.safs.natives.NativeWrapper -fileforgettime fullPathFileName > outputFile.txt

Parameters:

args - String[],
If IndependantLog.ARG_DEBUG is present, then show debug message on console
if ARG_FILE_FOR_GETTIME followed by a full path file name such as "c:\temp\myfile.txt", then test_getFileTime(String[])
if ARG_HOSTNAME followed by host name such as machine.domain.com, then test_getHostIp(String[])