From f4bbb2f167fa47b59bac9310ffcf757f291f02bd Mon Sep 17 00:00:00 2001
From: Doug MacEachern <dougm@hyperic.com>
Date: Fri, 23 Jul 2004 19:52:26 +0000
Subject: [PATCH] some ptql doc

---
 bindings/java/.sigar_shellrc                  |  6 ++-
 .../sigar/ptql/ProcessQueryBuilder.java       | 38 ++++++++++++++++++-
 2 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/bindings/java/.sigar_shellrc b/bindings/java/.sigar_shellrc
index 20a54aa7..32396959 100644
--- a/bindings/java/.sigar_shellrc
+++ b/bindings/java/.sigar_shellrc
@@ -2,20 +2,24 @@
 #commands in this file are run just as they would be if they
 #were typed in by hand in the shell prompt.
 
-#find weblogic nodes
+#find weblogic nodes (-1 means last index in the array)
 alias wlfind ptql State.Name.eq=java,Args.-1.eq=weblogic.Server
 
 #find jboss
 alias jbfind ptql State.Name.eq=java,Args.-1.eq=org.jboss.Main
 
 #find ers apache worker or prefork httpsd
+#($1 is the return value of the first query in the string)
 alias erfind ptql State.Name.sw=httpsd.,State.Name.Pne=$1
 
 #find ant processes (ant hangs on me sometimes)
+#(* matches any value in the array)
 alias hant ptql State.Name.eq=java,Args.*.eq=org.apache.tools.ant.Main
 
 #my HQ agent
+#(user.name is in System.getProperties)
 alias myag ptql CredName.User.eq=$user.name,State.Name.eq=java,Args.-1.ew=SpiderAgent
 
 #find all java procs except the shell itself
+#($$ is the current process id)
 alias java ptql State.Name.eq=java,Pid.Pid.ne=$$
diff --git a/bindings/java/src/net/hyperic/sigar/ptql/ProcessQueryBuilder.java b/bindings/java/src/net/hyperic/sigar/ptql/ProcessQueryBuilder.java
index 2db8454e..880ebdb0 100644
--- a/bindings/java/src/net/hyperic/sigar/ptql/ProcessQueryBuilder.java
+++ b/bindings/java/src/net/hyperic/sigar/ptql/ProcessQueryBuilder.java
@@ -24,6 +24,42 @@ import org.apache.bcel.generic.ObjectType;
 import org.apache.bcel.generic.PUSH;
 import org.apache.bcel.generic.Type;
 
+/**
+ * Build a Process Query using a PTQL string.
+ *
+ * Queries must be in the following format:
+ * <pre>
+ * Class.Attribute.operator=value
+ * </pre>
+ * Where:
+ * <ul>
+ * <li> <b>Class</b> is the name of the Sigar class minus the Proc prefix.
+ * <li> <b>Attribute</b> is an attribute of the given <b>Class</b>,
+ * index into an array or key in a Map class.
+ * <li> <b>operator</b> is one of the following for String values:
+ *   <ul>
+ *    <li> <b>eq</b> - Equal to <b>value</b>
+ *    <li> <b>ne</b> - Not Equal to <b>value</b>
+ *    <li> <b>ew</b> - Ends with <b>value</b>
+ *    <li> <b>sw</b> - Starts with <b>value</b>
+ *    <li> <b>ct</b> - Contains <b>value</b> (substring)
+ *    <li> <b>re</b> - Regular expression <b>value</b> matches
+ *   </ul>
+ * <li> <b>operator</b> is one of the following for numeric values:
+ *   <ul>
+ *    <li> <b>eq</b> - Equal to <b>value</b>
+ *    <li> <b>ne</b> - Not Equal to <b>value</b>
+ *    <li> <b>gt</b> - Greater than <b>value</b>
+ *    <li> <b>ge</b> - Greater than or equal <b>value</b>
+ *    <li> <b>lt</b> - Less than <b>value</b>
+ *    <li> <b>le</b> - Less than or equal <b>value</b>
+ *   </ul>
+ * </ul>
+ * Multiple queries must delimited by a comma.
+ * <p>
+ * Examples can be found in the sigar-bin/lib/.sigar_shellrc file of
+ * the Sigar distribution.
+ */
 public class ProcessQueryBuilder {
 
     //set true during development to dump generated
@@ -75,7 +111,7 @@ public class ProcessQueryBuilder {
     //branches of query method
     private ArrayList branches = new ArrayList();
 
-    public static final boolean COMPAT_1_4;
+    static final boolean COMPAT_1_4;
 
     static {
         //long