com.jezhumble.javasysmon
Class JavaSysMon

java.lang.Object
  extended by com.jezhumble.javasysmon.JavaSysMon
All Implemented Interfaces:
Monitor

public class JavaSysMon
extends java.lang.Object
implements Monitor

This class provides the main API for JavaSysMon. You must instantiate this class in order to use it, but it stores no state, so there is zero overhead to instantiating it as many times as you like, and hence no need to cache it.

When instantiated for the first time, JavaSysMon will discover which operating system it is running on and attempt to load the appropriate OS-specific extensions. If JavaSysMon doesn't support the OS you're running on, all calls to the API will return null or zero values. Probably the best one to test is osName.

You can run JavaSysMon directly as a jar file, using the command "java -jar javasysmon.jar", in which case it will display output similar to the UNIX "top" command. You can optionally specify a process id as an argument, in which case JavaSysMon will attempt to kill the process.

Author:
Jez Humble

Constructor Summary
JavaSysMon()
          Creates a new JavaSysMon object through which to access the JavaSysMon API.
 
Method Summary
 long cpuFrequencyInHz()
          Get the CPU frequency in Hz
 CpuTimes cpuTimes()
          Gets a snapshot which contains the total amount of time the CPU has spent in user mode, kernel mode, and idle.
 int currentPid()
          Gets the pid of the process that is calling this method (assuming it is running in the same process).
 void infanticide()
          Attempts to kill all the descendants of the currently running process.
 void killProcess(int pid)
          Attempts to kill the process identified by the integer id supplied.
 void killProcessTree(int pid, boolean descendantsOnly)
          Kills the process tree starting at the process identified by pid.
static void main(java.lang.String[] params)
          This is the main entry point when running the jar directly.
 int numCpus()
          Get the number of CPU cores.
 java.lang.String osName()
          Get the operating system name.
 MemoryStats physical()
          Gets the physical memory installed, and the amount free.
 ProcessInfo[] processTable()
          Get the current process table.
 OsProcess processTree()
          Gets the current process table in the form of a process tree.
static void setMonitor(Monitor myMonitor)
          Allows you to register your own implementation of Monitor.
 MemoryStats swap()
          Gets the amount of swap available to the operating system, and the amount that is free.
 long uptimeInSeconds()
          How long the system has been up in seconds.
 void visitProcessTree(int pid, ProcessVisitor processVisitor)
          Allows you to visit the process tree, starting at the node identified by pid.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JavaSysMon

public JavaSysMon()
Creates a new JavaSysMon object through which to access the JavaSysMon API. All necessary state is kept statically so there is zero overhead to instantiating this class.

Method Detail

setMonitor

public static void setMonitor(Monitor myMonitor)
Allows you to register your own implementation of Monitor.

Parameters:
myMonitor - An implementation of the Monitor interface that all API calls will be delegated to

main

public static void main(java.lang.String[] params)
                 throws java.lang.Exception
This is the main entry point when running the jar directly. It prints out some system performance metrics and the process table in a format similar to the UNIX top command. Optionally you can specify a process id as an argument, in which case JavaSysMon will attempt to kill the process specified by that pid.

Throws:
java.lang.Exception

osName

public java.lang.String osName()
Get the operating system name.

Specified by:
osName in interface Monitor
Returns:
The operating system name.

numCpus

public int numCpus()
Get the number of CPU cores.

Specified by:
numCpus in interface Monitor
Returns:
The number of CPU cores.

cpuFrequencyInHz

public long cpuFrequencyInHz()
Get the CPU frequency in Hz

Specified by:
cpuFrequencyInHz in interface Monitor
Returns:
the CPU frequency in Hz

uptimeInSeconds

public long uptimeInSeconds()
How long the system has been up in seconds. Doesn't generally include time that the system has been hibernating or asleep.

Specified by:
uptimeInSeconds in interface Monitor
Returns:
The time the system has been up in seconds.

currentPid

public int currentPid()
Gets the pid of the process that is calling this method (assuming it is running in the same process).

Specified by:
currentPid in interface Monitor
Returns:
The pid of the process calling this method.

cpuTimes

public CpuTimes cpuTimes()
Gets a snapshot which contains the total amount of time the CPU has spent in user mode, kernel mode, and idle. Given two snapshots, you can calculate the CPU usage during that time. There is a convenience method to perform this calculation in CpuTimes.getCpuUsage(com.jezhumble.javasysmon.CpuTimes)

Specified by:
cpuTimes in interface Monitor
Returns:
An object containing the amount of time the CPU has spent idle, in user mode and in kernel mode, in milliseconds.

physical

public MemoryStats physical()
Gets the physical memory installed, and the amount free.

Specified by:
physical in interface Monitor
Returns:
An object containing the amount of physical memory installed, and the amount free.

swap

public MemoryStats swap()
Gets the amount of swap available to the operating system, and the amount that is free.

Specified by:
swap in interface Monitor
Returns:
An object containing the amount of swap available to the system, and the amount free.

processTable

public ProcessInfo[] processTable()
Get the current process table. This call returns an array of objects, each of which represents a single process. If you want the objects in a tree structure, use processTree() instead.

Specified by:
processTable in interface Monitor
Returns:
An array of objects, each of which represents a process.

processTree

public OsProcess processTree()
Gets the current process table in the form of a process tree. The object returned is a top-level container which doesn't actually represent a process - its children are the top-level processes running in the system. This is necessary because some operating systems (Windows, for example) don't have a single top-level process (orphans are literally orphaned), and because the process table snapshot is not atomic. That means the process table thus returned can be internally inconsistent.

Returns:
The current process table in the form of a process tree.

killProcess

public void killProcess(int pid)
Attempts to kill the process identified by the integer id supplied. This will silently fail if you don't have the authority to kill that process. This method sends SIGTERM on the UNIX platform, and kills the process using TerminateProcess on Windows.

Specified by:
killProcess in interface Monitor
Parameters:
pid - The id of the process to kill

visitProcessTree

public void visitProcessTree(int pid,
                             ProcessVisitor processVisitor)
Allows you to visit the process tree, starting at the node identified by pid. The process tree is traversed depth-first.

Parameters:
pid - The identifier of the node to start visiting
processVisitor - The visitor

killProcessTree

public void killProcessTree(int pid,
                            boolean descendantsOnly)
Kills the process tree starting at the process identified by pid. The process tree is killed from the bottom up to ensure that orphans are not generated.

This method uses visitProcessTree(int, com.jezhumble.javasysmon.ProcessVisitor).

Parameters:
pid - The identifier of the process at which to start killing the tree.
descendantsOnly - Whether or not to kill the process you start at, or only its descendants

infanticide

public void infanticide()
Attempts to kill all the descendants of the currently running process.



Copyright © 2009 ThoughtWorks. All Rights Reserved.