From d507b2be83da67e2f51674269870d9b41078c5c5 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Ale=C5=A1=20K=C5=99enek?= <ljocha@ics.muni.cz>
Date: Fri, 25 Feb 2005 14:37:06 +0000
Subject: [PATCH] better documentation again

---
 org.glite.lb.ws-interface/src/LB.xml.T    |  84 +++++++++++++++++++++++-
 org.glite.lb.ws-interface/src/puke-ug.xsl | 102 ++++++++++++++++++++----------
 2 files changed, 152 insertions(+), 34 deletions(-)

diff --git a/org.glite.lb.ws-interface/src/LB.xml.T b/org.glite.lb.ws-interface/src/LB.xml.T
index 6f5895e..4471e92 100644
--- a/org.glite.lb.ws-interface/src/LB.xml.T
+++ b/org.glite.lb.ws-interface/src/LB.xml.T
@@ -9,18 +9,20 @@
 	ns="http://glite.org/wsdl/services/lb"
 	prefix="lb">
 
-	Keeping track of state of grid jobs.
+LB web service interface currently reflects the functionality of legacy
+LB query API. 
+
 
 	<types ns="http://glite.org/wsdl/types/lb" prefix="lbt">
 		<flags name="jobFlags">
 			Flags determining which fields of job status should be retrieved.
-			Can be combined arbitrarily.
 			<val name="CLASSADS">Include also long job descriptions (JDL).</val>
 			<val name="CHILDREN">Return list of subjobs of a DAG.</val>
 			<val name="CHILDSTAT">Return state of the subjobs, i.e. apply other flags recursively </val>
 		</flags>
 
 		<enum name="statName">
+			Classification of job states.
 @@@{
 	for my $stat ($status->getTypesOrdered) {
 		my $u = uc $stat;
@@ -40,6 +42,7 @@
 			$n = $1.ucfirst $2 while $n =~ /([[:alpha:]]*)_([[:alpha:]]*)/;
 				gen qq{
 !		<enum name="$n">
+!			Auxiliary type; values of the jobStatus.$n field.
 };
 				for (@{$f->{codes}}) {
 					my $uc = uc $_->{name};
@@ -104,6 +107,7 @@
 
 		<struct name="genericFault" fault="yes">
 			Generic SOAP fault, used to deliver any LB errors.
+			May be returned by any of the operations.
 			<elem name="source" type="xsd:string">Source component (module) of the error.</elem>
 			<elem name="code" type="xsd:int">Numeric error code.</elem>
 			<elem name="text" type="xsd:string">Error text corresponding to the code.</elem>
@@ -114,6 +118,55 @@
 		<simple name="string"/>
 		<simple name="int"/>
 
+		<struct name="queryConditions">
+			An element of outer list of query conditions in job queries.
+			It expresses possibly several conditions (records) on a single job attribute.
+			These conditions are logically OR-ed.
+			<elem name="attr" type="queryAttr"> The job attribute to which the query conditions apply. </elem>
+			<elem name="tagName" type="string" optional="yes"> Name of the queried user tag if attr is USERTAG.</elem>
+			<elem name="statName" type="statName" optional="yes"> Name of the job state to which "attr = TIME" condition refers.</elem>
+			<elem name="record" type="queryRecord" list="yes"> The conditions. </elem>
+		</struct>
+
+		<enum name="queryAttr">
+			Specification of a job attribute in query.
+			<val name="JOBID">A concrete JobId</val>
+			<val name="OWNER">Owner of the job (X509 certificate subject).</val>
+			<val name="STATUS">Status of the job (see statName type).</val>
+			<val name="LOCATION">Where the job is currently handled (hostname).</val>
+			<val name="DESTINATION">Where the job is or was scheduled to be executed.</val>
+			<val name="DONECODE">How the job terminated (see doneCode type)</val>
+			<val name="USERTAG">Value of particular user tag. The tag name has to be specified in queryConditions.tagName.</val>
+			<val name="TIME">When the job entered a particular state. The state has to be specified in queryCondition.statName.</val>
+			<val name="RESUBMITTED">The job was resubmitted.</val>
+			<val name="PARENT">JobId of the job parend (DAG).</val>
+			<val name="EXITCODE">UNIX exit code of the job.</val>
+		</enum>
+
+		<struct name="queryRecord">
+			A single query condition.
+			<elem name="op" type="queryOp"> Relational operator of the condition.</elem>
+			<elem name="value1" type="queryRecValue"> Value to compare the attribute with.</elem>
+			<elem name="value2" type="queryRecValue" optional="yes"> Another value to compare the attribute with (op = WITHIN only).</elem>
+		</struct>
+
+		<enum name="queryOp">
+			Relational operator of query conditions.
+			<val name="EQUAL"> Attribute is equal to the specified value </val>
+			<val name="LESS"> Attribute is less than the specified value or equal </val>
+			<val name="GREATER"> Attribute is greater than the specified value or equal </val>
+			<val name="WITHIN"> Attribute is withing a range (queryRecord.value2 must be specified) </val>
+			<val name="UNEQUAL"> Attribute is not equal to the specified value.</val>
+		</enum>
+
+		<struct name="queryRecValue">
+			A value to compare an attribute with in queries.
+			Exactly one of the elements must be specified.
+			<elem name="i" type="int">Integer.</elem>
+			<elem name="c" type="string">String.</elem>
+			<elem name="t" type="timeval">Timestamp.</elem>
+		</struct>
+
 	</types>
 
 
@@ -126,4 +179,31 @@
 		<fault name="genericFault" type="genericFault"> Any error. </fault>
 	</op>
 
+	<op name="QueryJobs">
+		Retrieve a list of jobs, including their states, based on
+		query conditions.
+		The conditions take the form of a list of lists.
+		Elements of the inner lists refer to a single job attribute, the conditions are or-ed.
+		Elements of the outer list may refer to different job attributes, they are and-ed.
+
+		<input name="conditions" type="queryConditions" list="yes">The query conditions.</input>
+		<input name="flags" type="jobFlags"> Which data fields to retrieve.</input>
+		<output name="jobs" type="string" list="yes"> JobId's of jobs matching the query.</output>
+		<output name="states" type="jobStatus" list="yes"> States of jobs matching the query.</output>
+		<fault name="genericFault" type="genericFault"> Any error. </fault>
+	</op>
+
+	<op name="GetVersion">
+		Return version of the service.
+		<output name="version" type="string">Returned version.</output>
+		<fault name="genericFault" type="genericFault"> Any error. </fault>
+	</op>
+
+	<op name="UserJobs">
+		Simplified query, return all jobs of the authenticated user.
+		<output name="jobs" type="string" list="yes"> JobId's of jobs matching the query.</output>
+		<output name="states" type="jobStatus" list="yes"> States of jobs matching the query.</output>
+		<fault name="genericFault" type="genericFault"> Any error. </fault>
+	</op>
+
 </service>
diff --git a/org.glite.lb.ws-interface/src/puke-ug.xsl b/org.glite.lb.ws-interface/src/puke-ug.xsl
index 14c558d..2536d40 100644
--- a/org.glite.lb.ws-interface/src/puke-ug.xsl
+++ b/org.glite.lb.ws-interface/src/puke-ug.xsl
@@ -11,12 +11,11 @@
 
 	<chapter>
 		<title><xsl:value-of select="@name"/></title>
-		<para> <xsl:value-of select="text()"/> </para>
 		<sect1>
 			<title>Operations</title>
-				<itemizedlist>
-					<xsl:apply-templates select="op"/>
-				</itemizedlist>
+				<xsl:apply-templates select="op">
+					<xsl:sort select="@name"/>
+				</xsl:apply-templates>
 		</sect1>
 	
 		<sect1>
@@ -28,57 +27,92 @@
 	
 </xsl:template>
 
+<xsl:template match="input|output|fault">
+	<varlistentry>
+		<term>
+			<type>
+				<xsl:choose>
+					<xsl:when test="@type!='string' and @type!='int'">
+						<link linkend="type:{@type}">
+							<xsl:value-of select="@type "/>
+						</link>
+					</xsl:when>
+					<xsl:otherwise>xsd:<xsl:value-of select="@type "/></xsl:otherwise>
+				</xsl:choose>
+			</type>
+			<parameter><xsl:value-of select="@name"/></parameter>
+		</term>
+		<listitem>
+			<simpara><xsl:value-of select="text()"/></simpara>
+		</listitem>
+	</varlistentry>
+</xsl:template>
+
 <xsl:template match="op" >
-	<listitem>
+	<sect2 id="op:{@name}">
+		<title><xsl:value-of select="@name"/></title>
+		<para><xsl:value-of select="text()"/></para>
 		<para>
-		<funcsynopsis>
-			<funcprototype>
-				<funcdef>
-					<xsl:value-of select="./output/@type"/>
-					<function>
-						<xsl:value-of select="@name"/>
-					</function>
-				</funcdef>
-				<xsl:for-each select="./input">
-					<paramdef>
-						<xsl:value-of select="@type "/>
-						<parameter><xsl:value-of select="@name"/></parameter>
-					</paramdef>
-				</xsl:for-each>
-			</funcprototype>
-		</funcsynopsis>
+			Inputs:
+			<xsl:choose>
+				<xsl:when test="count(./input)>0">
+					<variablelist>
+						<xsl:apply-templates select="./input"/>
+					</variablelist>
+				</xsl:when>
+				<xsl:otherwise>N/A</xsl:otherwise>
+			</xsl:choose>
 		</para>
-		<para> <xsl:value-of select="text()"/> </para>
-	</listitem>
-</xsl:template>
-
-<xsl:template match="op" mode="detail">
+		<para>
+			Outputs:
+			<variablelist>
+				<xsl:apply-templates select="./output"/>
+			</variablelist>
+		</para>
+	</sect2>
 </xsl:template>
 
 <xsl:template match="types">
 	<xsl:for-each select="flags|enum|struct">
 		<xsl:sort select="@name"/>
-		<sect2>
+		<sect2 id="type:{@name}">
 			<title> <xsl:value-of select="@name"/> </title>
+			<para> <xsl:value-of select="text()"/> </para>
 			<xsl:choose>
 				<xsl:when test="name(.)='struct'">
 					<para> <emphasis>Structure</emphasis> (sequence complex type in WSDL)</para>
+					<para> Fields: ( <type>type </type> <structfield>name</structfield> description )</para>
 				</xsl:when>
 				<xsl:when test="name(.)='enum'">
-					<para> <emphasis>Enumeration</emphasis> (restriction of xsd:string in WSDL)</para>
+					<para> <emphasis>Enumeration</emphasis> (restriction of xsd:string in WSDL),
+						exactly one of the values must be specified.
+					</para>
+					<para> Values: </para>
 				</xsl:when>
 				<xsl:when test="name(.)='flags'">
-					<para> <emphasis>Flags</emphasis> (sequence of restricted xsd:string in WSDL)</para>
+					<para> <emphasis>Flags</emphasis> (sequence of restricted xsd:string in WSDL),
+						any number of values can be specified together.
+					</para>
+					<para> Values: </para>
 				</xsl:when>
 			</xsl:choose>
-			<para> <xsl:value-of select="text()"/> </para>
 			<variablelist>
 				<xsl:for-each select="elem|val">
 					<varlistentry>
 						<term>
 							<xsl:choose>
 								<xsl:when test="name(.)='elem'">
-									<type><xsl:value-of select="@type"/></type>
+									<type>
+										<xsl:choose>
+											<xsl:when test="@type!='string' and @type!='int' and @type!='xsd:string' and @type!='xsd:int' and @type!='xsd:boolean' and @type!='xsd:long'">
+												<link linkend="type:{@type}">
+													<xsl:value-of select="@type "/> 
+												</link>
+											</xsl:when>
+											<xsl:otherwise><xsl:value-of select="@type "/></xsl:otherwise>
+										</xsl:choose>
+									</type>
+									<!-- <type><xsl:value-of select="@type"/></type> -->
 									<xsl:value-of select="' '"/>
 									<structfield><xsl:value-of select="@name"/></structfield>
 								</xsl:when>
@@ -88,7 +122,11 @@
 							</xsl:choose>
 						</term>
 						<listitem>
-							<simpara><xsl:value-of select="text()"/></simpara>
+							<simpara>
+								<xsl:if test="@optional = 'yes'"> (optional) </xsl:if>
+								<xsl:if test="@list = 'yes'"> (multiple occurence) </xsl:if>
+								<xsl:value-of select=" text()"/>
+							</simpara>
 						</listitem>
 					</varlistentry>
 				</xsl:for-each>
-- 
1.8.2.3