org.rhq.core.system.pquery

Class ProcessInfoQuery

java.lang.Object

org.rhq.core.system.pquery.ProcessInfoQuery

public class ProcessInfoQuery
extends Object

Performs a query over a set of command line strings. The query strings are written in the Process Info Query Language (PIQL, pronounced pickle).In effect, your PIQL will examine a list of running processes whose command lines match a certain set of criteria. PIQL statements are formatted by a series of criteria, with each criteria separated with a comma:

CRITERIA[,CRITERIA]*

Criteria are formatted in the following manner:

CONDITIONAL=VALUE

VALUE is either a regular expression or a pid filename to compare a value obtained using the CONDITIONAL. See the class javadoc for java.util.regex.Pattern to learn the syntax of valid regular expressions. A CONDITIONAL is defined as:

CATEGORY|ATTRIBUTE|OPERATOR[|QUALIFIER]

where:

• CATEGORY is either process or arg
• ATTRIBUTE declares what is to be matched; value depends on the category - see below
• OPERATOR is the conditional check made against the given VALUE - see below
• QUALIFIER is an optional query flag; parent is the only value currently allowed

The ATTRIBUTE can be one of the following:

• If CATEGORY is process:
  • name - the full path of the executable (i.e. the full string of the first command line argument)
  • basename - just the executable filename (not including any path information)
  • pidfile - the contents of a file, assumed to be a single number representing a pid
  • pid - the pid itself (allows you to match a process in which you already know its pid)
• If CATEGORY is arg:
  • <#> - a specific argument; this is an index in the process' command line arguments array (where argument 0 maps to the process name, -1 maps to the last argument)
  • * - a literal asterisk means any argument can match
  • <argname> - the name of the argument (e.g. "-b", "--port", "verbose")

The OPERATOR can be one of the following:

• match - the VALUE regular expression must match
• nomatch - the VALUE regular expression must not match

Some examples of PIQL are:

PIQL	What is matched
process|pidfile|match=/etc/product/lock.pid	the process whose pid matches the number found in the lock.pid file
process|pidfile|match|parent=/etc/product/lock.pid	child processes of the parent process whose pid matches the number found in the lock.pid file
process|name|match=^/foo.*	all processes whose executables are found under the root "foo" directory
process|basename|match=^java.*	all processes whose executable file has "java" at the start of it
process|basename|match=(?i)^java.*	all processes whose executable file has "java" at the start of it (case insensitive, so "JAVA" would also match)
process|name|match=.*(product|java).*	all processes whose executable paths have either "product" or "java" in them
process|name|match=^C:.*,process|basename|nomatch=java.exe	all processes whose executables are found on the Windows C: drive but is not a "java.exe" process
arg|1|match=org\.jboss\.Main	all processes whose command line argument #1 has a value of "org.jboss.Main". This will NOT match a process that does not have a command line argument at the given index.
arg|*|match=.*daemon.*	all processes whose command lines have any argument with the substring "daemon" in them
arg|-b|nomatch=127\.0\.0\.1	all processes whose command lines have any argument named "-b" whose value is not "127.0.0.1" (e.g. "-b 192.168.0.5"). This will NOT match a process that does not have that argument at all.
arg|-Dbind.address|match=127.0.0.1	all processes whose command lines have any argument named "bind.address" whose value is "127.0.0.1" (e.g. "-Dbind.address=127.0.0.1"). This will NOT match a process that does not have that argument at all.
arg|-cp|match=.*org\.abc\.Class.*	all processes whose command lines have any argument named "-cp" whose value contains "org.abc.Class". This will NOT match a process that does not have that argument at all.
arg|org.jboss.Main|match=.*	all processes whose command lines have any argument named "org.jboss.Main"
process|basename|match=(?i)Apache.exe,arg|-k|match|parent=runservice	all Apache processes that are running as child processes to the main Apache service.
process|basename|nomatch|parent=exec	all processes that have a parent whose basename is not exec. This will match all processes that do not have a parent.
process|basename|match=^(https?d.*|[Aa]pache)$,process|name|nomatch|parent=^(https?d.*|[Aa]pache)$	all Apache processes that do not have a parent process that is also an Apache process (i.e. this eliminates all of the httpd child processes and only returns the main Apache servers). This will match a process that does not have a parent but has a basename of Apache.
process|pid|match=1016	The process whose pid is 1016.

Author:

John Mazzitelli

Constructor Summary

Constructors

Constructor and Description
ProcessInfoQuery(List<ProcessInfo> processes) Constructor for ProcessInfoQuery given an collection of process information that represents the processes currently running.

Method Summary

Methods

Modifier and Type	Method and Description
List<ProcessInfo>	getProcesses() Returns the list of all the processes that this object will query against.
List<ProcessInfo>	query(String query) Performs a query on the set of known processes where query defines the criteria.

Methods inherited from class java.lang.Object

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

Constructor Detail

ProcessInfoQuery

public ProcessInfoQuery(List<ProcessInfo> processes)

Constructor for ProcessInfoQuery given an collection of process information that represents the processes currently running. Think of the processes data as coming from part of the output you see in the typical UNIX "ps" command.

Parameters:

processes -

See Also:

NativeSystemInfo.getAllProcesses()

Method Detail

getProcesses

public List<ProcessInfo> getProcesses()

Returns the list of all the processes that this object will query against.

Returns:

all processes this object knows about

query

public List<ProcessInfo> query(String query)

Performs a query on the set of known processes where query defines the criteria.

Parameters:

query - the query string containing the criteria to match

Returns:

the matches processes' command lines

Throws:

IllegalArgumentException - if the query was invalid