From: Jiří Sitera Date: Thu, 22 Jun 2006 15:43:45 +0000 (+0000) Subject: Use cases added X-Git-Tag: gridsite-core_R_1_3_2~90 X-Git-Url: http://scientific.zcu.cz/git/?a=commitdiff_plain;h=b03bd25463f7c6e8ecf0c34c161df16599a29bcd;p=jra1mw.git Use cases added --- diff --git a/org.glite.jp/doc/users-quide/JP-users-guide.tex b/org.glite.jp/doc/users-quide/JP-users-guide.tex index 3d8fc9c..4521af3 100644 --- a/org.glite.jp/doc/users-quide/JP-users-guide.tex +++ b/org.glite.jp/doc/users-quide/JP-users-guide.tex @@ -12,13 +12,18 @@ \Dissemination{PUBLIC} \DocumentLink{} -\Abstract{This user's guide is intended for a user of the Job - Provenance (JP) service. The service architecture characteristic is - followed by description of main JP use case scenarios. Technical +\Abstract{ + + Job Provenance (JP) service provides long-term storage of data + related to job live in a Grid. JP provides a query interface + allowing to perform data-mining. The possibility to annotate jobs + stored in JP is also provided. + + There is a overview of the service architecture followed by main JP + use case scenarios in this document. Technical reference documentation for both JP user and JP administrator is included in - this document too. This version of user's guide is part of the - first release of JP and it also contains release notes describing - corrent limitations of JP implementation.} + this document too. This user's guide also contains release notes + describing current JP implementation.} \def\todo#1{\textbf{TODO:} #1} @@ -54,7 +59,7 @@ their interaction with the Job Provenance. \begin{figure}[htpb] \centering - \includegraphics[scale=0.5]{JP-interactions} + \includegraphics[scale=0.7]{JP-interactions} \caption{Data flow into gLite Job Provenance} \label{fig:psinter} \end{figure} @@ -74,7 +79,7 @@ queries. A user query part of JP is shown in Fig.~\ref{fig:query}. \begin{figure}[htpb] \centering - \includegraphics[scale=0.5]{JP-query} + \includegraphics[scale=0.8]{JP-query} \caption{Index Server interactions} \label{fig:query} \end{figure} @@ -88,21 +93,185 @@ Primary Storages and vice versa. The interface exposed by JPIS to the end user is described in the chapter~\ref{reference}. Command line interface tool for end-user -interface to the JPIS is described in the chapter~\ref{CLI}. - +interface to the JPIS is described in the chapter~\ref{CLI}. See the +next chapter (use cases) for futher description of JP to user +interactions. \section{Job Provenance use cases} -\todo{In next release} + +\subsection{Prerequisities} + +\subsubsection{LB/JP relationship} +When JP deployed, any job in a terminal state will disappear from LB +after preconfigured timeout (one week for example). If a user wants +any information about such a job before this timeout (or before it +reach a terminal state) he must use the LB service (please refer to LB +user's guide). After that timeout he must use the JP service. + +\subsubsection{JP service location} +To call JP you need to know JP services address. There are two services: +\begin{itemize} +\item JP primary storage (JPPS)\\ + From JP design point of view there are only few PS in the + grid. Expected implementation is that these JPPS locations + are preconfigured in a UI instance while one of them is configured as + default JPPS. +\item JP index server (JPIS)\\ + Each index server is build (configured and started) by site/VO/user + group administrator (or even "senior user") based on given + community needs (expected queries and its optimization). So in + principle the index server location for a given query is to be + provided by the user. We expect that the UI instance will provide + mechanism allowing selection from preconfigured JPIS servers list. +\end{itemize} + +\subsection{JP use case 1 -- get job info} + +The scenario: +\begin{itemize} +\item The user wants information about a particular job. He knows a + job id. Job isn't longer in the LB. Procedure: Ask the JPPS to get all + or selected attributes of job. +\end{itemize} + +The implementation: +\begin{itemize} + \item Let a user to specify attributes to be returned. See section + \ref{attributes}. + \item Call GetJobAttributes operation of a JPPS and display the values + returned. +\end{itemize} + +Examples and hints: +\begin{itemize} + \item \texttt{org.glite.jp.primary/examples/jpps-test.c}\\ + This utility is used for all JPPS operations. Some hints how to use it + can be find in the test plan document. +\end{itemize} + +\subsection{JP use case 2 -- get job files} + +The scenario: +\begin{itemize} + \item The user knows a job id, job is in a terminal state. The user wants + all files (LB event dump, sandbox) stored by JP for futher processing. +\end{itemize} + +The implementation: +\begin{itemize} + \item Call GetJobFiles operation of a JPPS. You will get a list of URLs + which can be used to download the files. +\end{itemize} + +Examples and hints: +\begin{itemize} + \item The same as use case 1. +\end{itemize} + +\subsection{JP use case 3 -- job lookup} + +The scenario: +\begin{itemize} + \item The user is looking for jobs with specific properties. In this case + (no job id known) a JPIS must be used. There are the same query interface + provided by any JPIS but if a particular query can be answered by + the given JPIS depends on its configuration (configuration + determines which attributes are uploaded by PS to IS, and which of + them are indexed). + \item The user should know the proper JPIS to use for its particular + needs. + \item The scenario can continue by the JP use cases number 1 and 2 described + above (JPIS answer will contain job ids and identification of JPPSs + to ask for all available JP data about the jobs). +\end{itemize} + +The implementation: +\begin{itemize} + \item The user will select a JPIS and provide query. The JPIS operation + QueryJobs is called and list of jobs matching the query is returned. +\end{itemize} + +Examples and hints: +\begin{itemize} + \item JPIS CLI tool\\ + org.glite.jp.index/examples/jpis-client.c + + \item example in org.glite.jp.index/examples/jpis-test.c (starting + from line 161) +\end{itemize} + +\subsection{JP use case 4 -- job annotation} + +The scenario: +\begin{itemize} + \item The user wants to add a user tag (annotation) to a job. He must know + the job id(s) (or use the JP use case number 3 to find it). +\end{itemize} + +The implementation: +\begin{itemize} + \item Call RecordTag operation of JPPS for the job(s) to add requested + user tag. +\end{itemize} + +Examples and hints: +\begin{itemize} + \item The same as use case 1. +\end{itemize} + + +\subsection{Job attributes} +\label{attributes} +Job attributes are referenced by its names. Each attribute belongs to +one namespace (represented by a prefix in the attribute name). + +A namespace is defined by a service (currently we have one for LB and +one for JP) providing its data to the JP or a user group/experiment +etc. who wants to attach its own data to the job. + +It is expected that UI have preconfigured list of available namespaces +and XML schema for each namespace (the schema can be automatically +retrieved based on the namespace name). A list of available attributes +is generated from these schemas when user have to select attributes to +be retrieved from JP. + +\begin{itemize} + \item The namespaces (schema is available at the URL representing namespace):\\ + http://egee.cesnet.cz/en/Schema/LB/Attributes\\ + http://egee.cesnet.cz/en/Schema/JP/System <<<<<<<(NOT YET)\\ + \item There are header files with known names of attributes generated from + these schema files in our build procedure:\\ + org.glite.lb.server/build/jp\_job\_attrs.h\\ + org.glite.jp.common/interface/known\_attr.h <<<<<<<\\ +\end{itemize} + +\subsection{Authentication and authorization} +All the calls must be authenticated by user credentials. In the +current JP release only implicit ACLs are available -- the job +information is available for job owner only. + \section{Release notes} \todo{TBD} -\section{Documentation for JP users} +\section{References} %\subsection{Role of the JP administrator} % Podle Ljochy sem nepatøí. Podle mne musí u¾ivatel vìdìt kdy a s èím % otravovat administratora (zejména IS). +In general, the page \texttt{http://egee.cesnet.cz/en/JRA1} should +contain actual versions of JP documentation. + +Interfaces (WS): +\begin{itemize} + \item In source code tree the WSDLs are located in these files:\\ + \texttt{org.glite.jp.ws-interface/src/JobProvenanceIS.xml,\\ + org.glite.jp.ws-interface/src/JobProvenancePS.xml,\\ + org.glite.jp.ws-interface/src/JobProvenanceTypes.xml + } +\end{itemize} + \subsection{Command line interface (CLI)} \label{CLI} {