From: <bd...@us...> - 2011-03-31 08:11:26
|
Revision: 9645 http://unicore.svn.sourceforge.net/unicore/?rev=9645&view=rev Author: bdemuth Date: 2011-03-31 08:11:16 +0000 (Thu, 31 Mar 2011) Log Message: ----------- Added Paths: ----------- eclipseclient/trunk/plugins/org.chemomentum.rcp.help.basic/customBuildCallbacks.xml eclipseclient/trunk/plugins/org.chemomentum.rcp.help.basic/src/doc/RichClient.txt Added: eclipseclient/trunk/plugins/org.chemomentum.rcp.help.basic/customBuildCallbacks.xml =================================================================== --- eclipseclient/trunk/plugins/org.chemomentum.rcp.help.basic/customBuildCallbacks.xml (rev 0) +++ eclipseclient/trunk/plugins/org.chemomentum.rcp.help.basic/customBuildCallbacks.xml 2011-03-31 08:11:16 UTC (rev 9645) @@ -0,0 +1,202 @@ +<!-- ===================================================================== --> +<!-- Custom targets called from a project's generated build.xml --> +<!-- Set customBuildCallbacks=<path/to/this/file> in your build.properties.--> +<!-- ===================================================================== --> +<project name="Build specific targets and properties" default="noDefault"> + + <property name="u6.svn.repo" value="http://unicore.svn.sourceforge.net/svnroot/unicore/" /> + <property name="documentation.dir" value="documentation" /> + <property name="documentation.tag" value="trunk" /> + + + <!-- ===================================================================== --> + <!-- Default target --> + <!-- ===================================================================== --> + <target name="noDefault"> + <echo message="This file must be called with explicit targets" /> + </target> + + <!-- ===================================================================== --> + <!-- Steps to do before the target build.jars --> + <!-- Available parameters : --> + <!-- build.result.folder - folder to contain the build results --> + <!-- ===================================================================== --> + <target name="pre.build.jars"> + + </target> + + <!-- ===================================================================== --> + <!-- Steps to do after the target build.jars --> + <!-- Available parameters : --> + <!-- build.result.folder - folder to contain the build results --> + <!-- ===================================================================== --> + <target name="post.build.jars"> + + </target> + + <!-- ===================================================================== --> + <!-- Steps to do before the target build.sources --> + <!-- Available parameters : --> + <!-- build.result.folder - folder to contain the build results --> + <!-- ===================================================================== --> + <target name="pre.build.sources"> + </target> + + <!-- ===================================================================== --> + <!-- Steps to do after the target build.sources --> + <!-- Available parameters : --> + <!-- build.result.folder - folder to contain the build results --> + <!-- ===================================================================== --> + <target name="post.build.sources"> + + </target> + + <!-- ===================================================================== --> + <!-- Steps to do before the compilation target <name> --> + <!-- Substitute "name" with the name of the compilation target, eg @dot --> + <!-- Available parameters : --> + <!-- source.foldern : n = 1 ... N, the source folders --> + <!-- target.folder : where the results of the compilation go --> + <!-- <name>.classpath : name = name of the compilation target. A --> + <!-- reference to the classpath structure. --> + <!-- ===================================================================== --> + <target name="pre.name"> + + </target> + + <target name="pre.@dot"> + + </target> + + <!-- ===================================================================== --> + <!-- Steps to do during the compilation target <name>, after the compile --> + <!-- but before jaring. Substitute "name" with the name of the compilation--> + <!-- target, eg @dot --> + <!-- Available parameters : --> + <!-- source.foldern : n = 1 ... N, the source folders --> + <!-- target.folder : where the results of the compilation go --> + <!-- <name>.classpath : name = name of the compilation target. A --> + <!-- reference to the classpath structure. --> + <!-- ===================================================================== --> + <target name="post.compile.name"> + </target> + + <target name="post.compile.@dot"> + </target> + + <!-- ===================================================================== --> + <!-- Steps to do after the compilation target <name> --> + <!-- Substitute "name" with the name of the compilation target, eg @dot --> + <!-- Available parameters : --> + <!-- jar.location - the location of the compilation results --> + <!-- <name>.classpath : name = name of the compilation target. A --> + <!-- reference to the classpath structure. --> + <!-- ===================================================================== --> + <target name="post.name"> + </target> + + <target name="post.@dot"> + </target> + + <!-- ===================================================================== --> + <!-- Steps to do before the target gather.bin.parts --> + <!-- Available parameters : --> + <!-- build.result.folder - folder containing the build results --> + <!-- target.folder - destination folder --> + <!-- ===================================================================== --> + <target name="pre.gather.bin.parts"> + + </target> + + <!-- ===================================================================== --> + <!-- Steps to do after the target gather.bin.parts --> + <!-- Available parameters : --> + <!-- build.result.folder - folder containing the build results --> + <!-- target.folder - destination folder --> + <!-- ===================================================================== --> + <target name="post.gather.bin.parts" depends="checkout.asciidoc.shared"> + <mkdir dir="${target.folder}/html/" /> + <echo> ... building HTML manual </echo> + + <copy todir="${target.folder}/html/images"> + <fileset dir="./src/doc/images" includes="*.png,*.gif,*.jpg,*.jpeg" defaultexcludes="no" /> + </copy> + + <exec dir="src/doc" executable="asciidoc" failonerror="false"> + <arg value="-e" /> + <arg value="-v" /> + <arg value="-f" /> + <arg value="${asciidoc.shared}/conf/asciidoc.conf" /> + <arg value="-f" /> + <arg value="${asciidoc.shared}/conf/xhtml11.conf" /> + <arg value="-a stylesheet="${asciidoc.shared}/unicoredoc.css"" /> + <arg value="-n" /> + <arg value="-a toc" /> + <arg value="-a imagewidth=700" /> + <arg value="-o"/> + <arg value="${target.folder}/html/RichClient.html" /> + <arg value="RichClient.txt" /> + </exec> + + + + </target> + + + + <!-- ===================================================================== --> + <!-- Steps to do before the target gather.sources --> + <!-- Available parameters : --> + <!-- destination.temp.folder - destination folder --> + <!-- ===================================================================== --> + <target name="pre.gather.sources"> + </target> + + <!-- ===================================================================== --> + <!-- Steps to do after the target gather.sources --> + <!-- Available parameters : --> + <!-- destination.temp.folder - destination folder --> + <!-- ===================================================================== --> + <target name="post.gather.sources"> + </target> + + <!-- ===================================================================== --> + <!-- Steps to do before the target gather.logs --> + <!-- Available parameters : --> + <!-- destination.temp.folder - destination folder --> + <!-- ===================================================================== --> + <target name="pre.gather.logs"> + </target> + + <!-- ===================================================================== --> + <!-- Steps to do after the target gather.logs --> + <!-- Available parameters : --> + <!-- destination.temp.folder - destination folder --> + <!-- ===================================================================== --> + <target name="post.gather.logs"> + </target> + + <!-- ===================================================================== --> + <!-- Steps to do before the target clean --> + <!-- Available parameters : --> + <!-- destination.temp.folder - destination folder --> + <!-- ===================================================================== --> + <target name="pre.clean"> + </target> + + <!-- ===================================================================== --> + <!-- Steps to do after the target clean --> + <!-- Available parameters : --> + <!-- plugin.destination - final destination of the build --> + <!-- build.result.folder - results of the compilation --> + <!-- temp.folder - temporary folder --> + <!-- ===================================================================== --> + <target name="post.clean"> + </target> + + <target name="checkout.asciidoc.shared"> + <property name="asciidoc.shared" value="${target.folder}/doc/shared" /> + <svn command="export" url="${u6.svn.repo}/${documentation.dir}/${documentation.tag}/shared" dest="${asciidoc.shared}" force="true"/> + </target> + +</project> Added: eclipseclient/trunk/plugins/org.chemomentum.rcp.help.basic/src/doc/RichClient.txt =================================================================== --- eclipseclient/trunk/plugins/org.chemomentum.rcp.help.basic/src/doc/RichClient.txt (rev 0) +++ eclipseclient/trunk/plugins/org.chemomentum.rcp.help.basic/src/doc/RichClient.txt 2011-03-31 08:11:16 UTC (rev 9645) @@ -0,0 +1,1680 @@ +UNICORE Rich Client user manual +=============================== +UNICORE Team <uni...@li...> +v6.4.0, February 2011 + +[[SECTION_INTRODUCTION]] +Introduction +------------ + +This document describes how to install and use the Eclipse based Rich Client for +the UNICORE workflow system. UNICORE is a European project that facilitates the +access to modern heterogeneous computer networks, so called `Grids'. It offers a +client-server framework for accessing Grid resources. It has a service oriented +architecture (<<SOA,SOA>>) which means that the functions of the software are +grouped into small coherent chunks (named `services') which can be installed on +different computer systems. + +The client software enables users to create descriptions of work to be performed +on the Grid, so called `jobs'. A single job usually corresponds to the execution +of a computer program on one of the available computer systems in the Grid. Once +a job has been created, the UNICORE Rich Client can submit it to a selected +computer system. The remote execution of the job can be monitored and output +files of the executed program can be downloaded to the user's computer. In order +to accomplish more complex tasks on the Grid, jobs can be embedded into +workflows. In our terminology, a workflow is a set of activities (the execution +of a single job would be considered an activity), interconnected by transitions +that define the order in which the activities must be performed. Workflows can +be created and edited graphically. Similar to jobs, they can be submitted to a +designated service on the Grid which executes them. Workflow execution can be +monitored in multiple ways and resulting output files can be downloaded to the +local harddisk. Apart from these basic features, the UNICORE Rich Client offers +a bunch of additional functions like browsing and monitoring services on the +Grid, managing user certificates, and transferring files to and from Grid +storages. + +This document is structured into three main parts: <<SECTION_INSTALLATION>> +describes the installation procedure and how to startup the client application. +<<SECTION_BASIC_USAGE>> tries to give a brief overview of the basic features and +most frequent use cases of this application. <<SECTION_REFERENCE>> provides a +reference guide to additional functions. + + +<<< +[[SECTION_INSTALLATION]] +Installation and Startup +------------------------ + +[[SUBSECTION_PREREQUISITES]] +Prerequisites +~~~~~~~~~~~~~ + +- Operating Systems: currently Linux and Microsoft Windows are supported. +footnote:[Eclipse's windowing toolkit, the Standard Widget Toolkit (SWT) +directly talks to the operating system's windowing system. While SWT loses its +platform independence through this approach, it allows for seamless integration +with the look and feel of different operating systems.] +- Java Runtime Environment: Sun Java 5 or higher is required. footnote:[Other +Java implementations (e.g. by GNU or IBM) are not supported.] + + +[[SUBSECTION_PROCEDURE]] +Procedure +~~~~~~~~~ + +- Download the installation archive that matches your operating system. + +- Unzip the archive to the desired location. + +- Run the executable called `UNICORE_Rich_Client.exe' (or `UNICORE_Rich_Client', +on a Unix/Linux machine). A splash screen will indicate the startup of the +client. + +- Specify location and passphrase of the keystore file that holds your +certificates (see <<SUBSECTION_BASIC_SECURITY>> for details about why this is +necessary). + + + +[[SECTION_BASIC_USAGE]] +Basic usage guide +----------------- + +[[SUBSECTION_WELCOME_SCREEN]] +Welcome screen +~~~~~~~~~~~~~~ + +When the client is started for the first time, it will display a welcome screen +that provides valuable information and helps in making the first steps with the +UNICORE Rich Client (see <<FIGURE_WELCOME_SCREEN>>). + +[[FIGURE_WELCOME_SCREEN]] +.The Welcome screen +image::images/welcome_screen.png[{imagewidth?width="{imagewidth}"}] + +The welcome screen is composed of several web pages that are displayed in the +internal web browser of the client: + +- The 'Overview' page highlight:1[] contains links to parts of this document and +the Eclipse framework's user manual. + +- The 'First Steps' page highlight:2[] helps in configuring the client for +accessing different Grids. + +- The 'Tutorials' page highlight:3[] offers links to Flash-based online +tutorials that will be displayed in a web browser. + +- The 'What's New' page highlight:4[] summarizes the most important new features +of the current client version and lists general UNICORE related news. + +A navigation bar on top of each page contains hyperlinks to the other pages. The +toolbar of the welcome screen can also be used to navigate back and forth +between the pages highlight:5[]. In order to leave the welcome screen and start +working with the client, click the 'Workbench' hyperlink highlight:6[]. The +welcome screen can later be re-opened via the 'Help -> Welcome' pull down menu +item. + + +[[SUBSECTION_WORKBENCH]] +The Eclipse workbench +~~~~~~~~~~~~~~~~~~~~~ + +The client's main window is called the 'workbench' (see <<FIGURE_WORKBENCH>>). +It has different components which can be opened, closed, resized, re-ordered and +even detached from the main window. + + +[[FIGURE_WORKBENCH]] +.The Eclipse workbench +image::images/workbench.png[{imagewidth?width="{imagewidth}"}] + + +[[SUBSUBSECTION_MENU_TOOL_BAR]] +Menu bar and tool bar +^^^^^^^^^^^^^^^^^^^^^ + +At the top of the workbench, there is a menu bar from which different pull down +menus containing `global' actions can be opened highlight:1[]. For convenience, +some actions are available via shortcuts from the tool bar just below the menu +bar. The items in the tool bar can change depending on the selection of objects +in the client, mirroring the fact that different actions can be performed on +different objects. + + +[[SUBSUBSECTION_VIEWS]] +Views +^^^^^ + +Resizeable and draggable tab panels containing buttons and other controls are an +integral part of all Eclipse based clients. These panels are called 'views' +highlight:2[]. Apart from being resized and moved, they can also be closed and +re-opened. Detaching a view from the workbench will embed the view in its own +window. Double-clicking its title will maximise it and double-clicking the title +once more will restore its original size. Some views are `singletons', so only +one instance of the view can be opened, whereas other views can be opened +multiple times, showing a different content in each instance. + + +[[SUBSUBSECTION_WORKSPACE]] +The workspace +^^^^^^^^^^^^^^ + +The workspace is a directory, usually located on the local hard drive +highlight:3[]. It is supposed to hold all relevant user data needed for the +daily work with an Eclipse-based client. Inside the workspace, the user data is +organised in subfolders, so-called 'projects'. All files within a project should +be thematically related. In the UNICORE Rich Client, each job description file +(with the extension `.job') and each workflow description file (`.flow' file) is +stored in its own project, together with its input files. +Having a separate project for each job or workflow has the following advantages: + +. Jobs and workflows can get complex. They may need a large number of input +files that might be organised in their own directory structure. Mixing up +multiple jobs or workflows in a single project can therefore lead to mixing up +input and/or output files. + +. Eclipse has its own notion of importing and exporting projects. This provides +a nice mechanism for exporting jobs and workflows (e.g. to a single zipped file +that contains all necessary input data) and sharing it with co-workers. In the +UNICORE Rich Client, job input files should be put into a directory called +`input files' inside the project. Relative paths can then be interpreted +relative to this directory, which makes sharing of projects very easy. + +Apart from the data that are relevant to the user, the workspace also contains +metadata that are used in order to manage user preferences and store the state +of the Eclipse workbench. +In the Eclipse framework, there are different views for displaying the content +of the workspace. The most widely used view is called the 'Navigator' view. It +represents the workspace as a file tree and is very similar to most graphical +file browsers. It can be used for creating, renaming, copying, and deleting +projects, files and directories. Projects can also be `closed' if unneeded. This +will hide their content from the Navigator view. + + +[[SUBSUBSECTION_EDITORS]] +Editors +^^^^^^^ + +When a file is supposed to be opened (e.g. after double clicking it in the +'Navigator' view, Eclipse tries to identify a suitable editor by looking at the +file's extension. If an associated editor can be found, it is invoked and will +display the file content. For example, `.txt' files invoke a text editor, the +`.flow' extension invokes the workflow editor highlight:4[]. File types can also +cause associated external applications to be started; for example, a web browser +for `.html' files. If the filetype is not supported, an error message is +displayed. Associations between file types and editors are defined in the +preference page that can be reached via 'Window -> Preferences -> General -> +Editors -> File Associations'. + + +[[SUBSUBSECTION_CONTEXT_MENUS]] +Context menus +^^^^^^^^^^^^^^ + +Many functions in the client are available via context menus highlight:5[]. In +order to open a context menu, right click an object or a view. The items +available in the context menu are different, depending on the object on which +the context menu was opened. + + +[[SUBSUBSECTION_PERSPECTIVES]] +Perspectives +^^^^^^^^^^^^ + +The outer appearance of the workbench is very flexible and can change a lot over +time. The user benefits from being able to hide information he does not want to +see at the moment and arrange the remaining components in a way that fits his +needs best. However, less experienced users may have to search for information +they accidentally hid in the first place. In order to deal with this problem, +the Eclipse framework has introduced the notion of 'perspectives'. +A perspective is a well defined arrangement of views and editors in the +workbench. In addition to determining which components are visible in which +spots, it can also influence the actions that can be performed from the tool bar +of the workbench. A given arrangement can be saved as a perspective for later +re-use and a user can always restore the original appearance of a perspective by +resetting the perspective. + + +[[SUBSECTION_BASIC_SECURITY]] +Basic security configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +[[SUBSUBSECTION_X509_ENCRYPTION]] +How does encryption with X.509 certificates work? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Most security mechanisms on a UNICORE Grid are based on X.509 certificates. For +each X.509 certificate, there is a pair of cryptographic keys, that fit each +other. These keys can be used to encrypt and decrypt messages: whatever has been +encrypted with one of the keys can only be decrypted with the other key - but +the keys are not equal. This is why this type of encryption is called +`asymmetric'. Such an asymmetric pair of keys can be used in a public key +infrastructure (PKI): The trick is that one of the two keys, called the `public' +key is published and therefore open to everyone, whereas the other key - called +the `private' key - is kept secret by the owner of the key pair. In order to be +able to keep the private key secret, it must be very difficult to reconstruct or +guess the private key by looking at the public key. + +Everyone can use the public key to encrypt messages that only the owner of the +private key can read. And, equally important, the owner of the private key can +prove that he owns the private key by encrypting a meaningful message with it: +everyone can use the public key to decrypt the message and make sure that it is +meaningful, but only the owner of the private key can produce the encrypted +message. Asymmetric encryption can also be used for digitally signing documents. +With a digital signature, a person can prove that he really is the author of a +document, or that he approves the content of a document. The most common way of +creating digital signatures comprises two steps: first, a checksum for the +document to be signed is computed. The checksum is a relatively short sequence +of characters (compared to the document). It is computed by applying a +well-known checksum function that always generates the same checksum as long as +the content of the document is unchanged. Second, the checksum is encrypted with +a private key. The encrypted checksum is published together with the document +and forms the digital signature. A reader of the document can use it for +checking whether the document was changed. To this end, he applies the same +checksum function to the document and compares the result to the checksum that +he obtains by decrypting the digital signature (using the public key). + +In order to obtain an X.509 certificate from a key pair, the public key is +stored in a document, together with some information about the certificate's +owner-to-be (e.g. name, email address, organisation). This document is then +digitally signed with the private key of a certificate authority (<<CA,CA>>), +which means that the CA approves the creation of the certificate. This process +is called `issuing a certificate'. Everyone can use the CA's public key to +check, whether the certificate has been signed by the CA. + + +[[SUBSECTION_UNICORE_X509]] +How does UNICORE use X.509 certificates? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +With X.509 certificates, UNICORE ensures two things: First, each client or +server on the Grid can attest that he is who he claims to be. He does so by +presenting his certificate - which contains the public key - and providing +evidence that he knows the private key belonging to this public key (by +encrypting a previously defined message). Since private keys are kept secret, he +must be the owner of the certificate. Second, the public key is used to encrypt +messages that only the person knowing the private key (the owner of the +certificate) can read. This way an encrypted communication channel between +different actors on the Grid is established (by secretly sending a newly created +key that can be used for both encryption and decryption of additional messages). +The protocol defining the details of establishing the encrypted channel is +called Transport Layer Security (TLS), a successor of the Secure Sockets Layer +(<<SSL,SSL>>). + + +[[SUBSUBSECTION_USER_X509]] +What does this mean to the user? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before accessing a UNICORE based Grid, each user needs to obtain a valid X.509 +certificate which is issued by one of the certificate authorities (CAs) that the +UNICORE servers trust. The client presents this certificate to the server +whenever he is asked for authentication. The server then checks whether it +trusts the CA that issued the certificate. It does so by searching for the CA's +certificate in a so-called `truststore' i.e. a file that contains a list of +trusted CAs' certificates. If the CA's certificate is found, it knows it can +trust the client. Analogously, the client checks whether it trusts the server. +If both checks are successful, a communication channel is created. + +All private keys for certificates that the user may want to use on the Grid are +stored in a special file called `keystore'. The keystore is encrypted and +secured by a passphrase that the user has to remember. During first startup, the +Rich Client can create a new keystore file. It is also possible to reuse an +existing keystore file. For simplicity, there is only one file that contains +both truststore and keystore, so the list of trusted CAs is written to the same +encrypted file that holds the private keys. + + +[[SUBSUBSECTION_TRUSTSTORE_VIEW]] +The Truststore view +^^^^^^^^^^^^^^^^^^^ + +Use this view to add certificates of trusted certificate authorities (CAs) to +the truststore (see <<FIGURE_TRUSTSTORE_VIEW>>). This is necessary in order to +communicate with secure Grid services via an SSL encrypted channel. Failing to +add the required certificates for the Grid infrastructure that you would like to +use will result in errors when trying to contact any of the Grid services. + +For each CA certificate contained in your keystore/truststore file, the +truststore view displays the alias identifying the certificate (must be unique), +the name of the CA, and the end of the certificate's validity period. + +In order to add trusted CA certificates, import a file containing these +certificates (the file extension should be one of `.jks', `.p12', or `.pem') +highlight:1[]. Certificates can also be removed from the truststore +highlight:2[]. Additional actions allow for opening a detailed certificate +description, changing a certificate's alias (used aliases must be unique) +exporting public keys to `.pem' files and setting the keystore password +highlight:3[]. + + +[[FIGURE_TRUSTSTORE_VIEW]] +.The Truststore view +image::images/truststore.png[{imagewidth?width="{imagewidth}"}] + + +[[SUBSUBSECTION_KEYSTORE_VIEW]] +The Keystore view +^^^^^^^^^^^^^^^^^ + +[[FIGURE_KEYSTORE_VIEW]] +.The Keystore view +image::images/keystore.png[{imagewidth?width="{imagewidth}"}] + +This view is used to manage private keys and the associated X.509 user +certificates (<<FIGURE_KEYSTORE_VIEW>>). Different actions may be performed via +the view's context menu highlight:1[]. The first item is used to import all +private and public keys from an existing keystore file into the client's +keystore. The second item can permanently delete private keys from the client's +keystore. Additional items allow for displaying more details about a selected +key, changing the alias that identifies the selected private key, exporting the +certificate that belongs to the selected private key, exporting a number of +private and public keys to an external keystore file and modifying the client +keystore's passphrase. In order to obtain a valid certificate from an existing +CA, a certificate request can be created. For each request, a pair of private +and public keys is generated. The private key is saved in the keystore. The +certificate request must be sent to the administrator(s) of a CA. The response +to such a request is usually a `.pem' file, containing the certificate, now +signed by the CA. By importing this file into the keystore (using the last item +in the context menu), the private key associated to the certificate becomes +functional. If the keystore contains multiple user certificates, a default +certificate for accessing Grid services should be set highlight:2[]. +This default certificate can later be overridden by the 'Security Profiles' view +(see <<SUBSUBSECTION_SECURITY_PROFILES_VIEW>>). + + +[[SUBSECTION_BROWSING_MONITORING]] +Browsing and monitoring the Grid +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +[[SUBSUBSECTION_GRID_BROWSER_VIEW]] +The Grid Browser view +^^^^^^^^^^^^^^^^^^^^^ + +This view represents the Grid as a tree structure (see +<<FIGURE_GRIDBROWSER_VIEW>>, top left). The items that form the tree are called +`nodes' and represent Grid services and files. + +[[FIGURE_GRIDBROWSER_VIEW]] +.The Grid Browser and Details views +image::images/grid_browser.png[{imagewidth?width="{imagewidth}"}] + +There are numerous actions that can be performed on this view or its nodes: + +. Adding registries: +For getting started, open the context menu (by right-clicking inside the Grid +Browser) and select 'add Registry' highlight:1[]. +In the appearing dialogue, enter the URL of a registry that serves as an entry +point to the Grid: A registry is used for looking up all available services. For +each added registry, a new node should appear just below the root node called +'Grid' highlight:2[]. + +. Refreshing nodes: +By double-clicking a node, the represented Grid service is contacted and +information about its state is gathered. This is called a 'refresh'. After +refreshing the registry, a new sub tree should open, displaying the target +system and workflow services known by the registry highlight:3[]. Target system +services are used for job execution, workflow services are used for workflow +execution. + +. Opening the context menu on a selected node: +By right-clicking a node, a context menu that contains all available actions for +the associated service will appear. For instance, users can create job +descriptions for job submission to a target system by selecting the 'create job' +action from the target system's context menu highlight:4[]. + +. Filtering of Grid services: +In large Grids, keeping an overview of the available services and finding +relevant information might become difficult. In order to support the user with +these tasks, configurable filters can be applied to the Grid Browser. Nodes that +do not pass the set of active filters, will not be displayed to the user. The +default filter shows job or workflow execution services and storages only. +Services that are less frequently used can be revealed by using the 'show' menu +to the top of the Grid Browser view highlight:5[] and selecting 'All services'. +Additional filters allow to search for services of a specific type, display jobs +and workflows that yield a particular state, or have been submitted within a +given period of time. A file search filter can be used to retrieve all files +that match a certain file name pattern. + +. Administrative actions: The Grid Browser offers additional actions like +creating and destroying Grid service instances. These can be made accessible by +increasing the detail level of the Grid Browser. To this end, select 'Window' -> +'Preferences' from the menu bar. A new window will pop up, that can be used for +specifying all sorts of preference settings (see +<<FIGURE_PREFERENCES_GENERAL>>). User preferences are discussed in more depth in +<<SUBSECTION_PREFERENCES>>. Grid specific settings can be made in the 'UNICORE' +category and its sub-categories. By setting the 'User Expertise Level' to +'expert', the additional administrative actions become available (see +<<FIGURE_PREFERENCES_UNICORE>>). + + +Although the Grid Browser displays the Grid as a tree, the actual topology of +the Grid can only be modelled with a graph. The Grid Browser deals with this +situation by depicting a single Grid service with multiple nodes. For instance, +a job that is part of a workflow will be represented by two different nodes in +the Grid Browser: one beneath the target system service that executed the job +and the other one beneath the workflow management service that corresponds to +the job's parent workflow. These two nodes, however, share the same data model: +whenever you refresh one of the nodes, the other one is being refreshed at the +same time. + + +[[SUBSUBSECTION_GRID_FILES]] +Grid Files +^^^^^^^^^^ + +Remote files in UNICORE based Grids are accessible through UNICORE storages that +can be searched directly in the Grid Browser. Directories and files are +displayed as child nodes of the storage node. Double-clicking a directory will +open it and list contained files and folders, while double-clicking a file will +download that file to the local hard disk and open its content in an associated +editor. Saving the file with the associated editor will also update the remote +file's content (except when the file is opened with an external editor). Data +can be moved between different remote file systems. For instance, you can move a +directory from one UNICORE storage to another with a single mouse drag. Files +can also be uploaded to remote storages by dragging them from the workspace, a +local file browser or the desktop. Due to a limitation of the Eclipse framework, +files can only be downloaded to the workspace (via the Navigator view). + + +[[SUBSUBSECTION_DETAILS_VIEW]] +The Details view +^^^^^^^^^^^^^^^^ + +When a node in the Grid Browser has been refreshed for the first time, +information about the associated service is shown in the 'Details' view +highlight:6[]. For target system services, this includes available resources +like number of CPUs, amount of main memory, and a list of installed +applications. For jobs and workflows, states and submission times are displayed, +for Grid files, sizes and modification dates. Note, that this view is connected +to the Grid Browser: Whenever a different node is selected, the 'Details' view +is being updated to display its details. + + +[[SUBSECTION_JOB_SUBMISSION]] +Job submission and visualisation of job outcomes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +[[SUBSUBSECTION_JOB_EDITOR]] +The Job editor +^^^^^^^^^^^^^^ + +The UNICORE Rich Client offers graphical editors for setting up job +descriptions. Instead of having to edit text-based job descriptions, the user is +provided high level interfaces which are taylored to the applications he wants +to execute on remote systems. The client is easily extensible with new +application specific user interfaces as new applications are introduced to the +Grid environment. Setting up a job description only requires a few simple steps +and can be performed within a couple of seconds. The first step is the creation +of a job project. + + +[[SUBSUBSECTION_JOB_PROJECT_CREATION]] +Creating a job project +^^^^^^^^^^^^^^^^^^^^^^ + +There are different ways to create a new job project: + +. Select 'File -> New -> Job Project' from the menu bar (see highlight:1[] in +<<FIGURE_CREATE_PROJECT>>). + +. Open the context menu of the 'Navigator' view and select 'New -> Job Project'. + +. Use the 'create job' item from the context menu of a target system node. + +. Choose the 'restore Job description' item from a job's context menu in the +Grid Browser. + +[[FIGURE_CREATE_PROJECT]] +.Creating a job or workflow project +image::images/create_project.png[{imagewidth?width="{imagewidth}"}] + +The first three of these options will pop up a series of wizard dialogs which +will guide the user through the creation of the job project (see +<<FIGURE_JOB_CREATION_WIZARD>>). + +[[FIGURE_JOB_CREATION_WIZARD]] +.Wizard for creating a job project +image::images/job_creation_wizard.png[{imagewidth?width="{imagewidth}"}] + +The first step of the wizard is used to choose an application to be run on the +target system. In our example, we would like to execute a simple shell script. +Therefore, we have selected the 'Script' application highlight:1[]. By pressing +the 'Finish' button the new job project is created. Click 'Next' which will take +you to the next wizard step. Here, a different name for the project +highlight:2[] and the job file highlight:3[] can be set. The third wizard page +allows for selecting a different target system for job submission highlight:4[]. +The selected target system can also be modified after the project has been +created. When the job is created with the last option, both the target system +selection and application to be run are restored from the server. Therefore, the +job creation wizard shows the second wizard page, only (where you can set names +for the project and job file). + + +[[SUBSUBSECTION_JOB_EDITING]] +Editing mode +^^^^^^^^^^^^ + + +The most convenient way to create a job project is using the context menu of a +target system node (see highlight:1[] in <<FIGURE_JOB_SUBMISSION>>), as the +corresponding target system will be pre-selected and the job creation wizard can +be completed on the first page. + +[[FIGURE_JOB_SUBMISSION]] +.Job editing and submission +image::images/job_submission.png[{imagewidth?width="{imagewidth}"}] + +Once the job project and job file have been created, a new 'job editor' will be +opened in editing mode, displaying a graphical user interface (<<GUI,GUI>>) for +the application highlight:2[]. It allows for defining the input parameters of +the job to be run. The GUI for the Script application provides an embedded text +editor for typing in the shell script highlight:3[]. New application GUIs can be +installed by selecting 'Help -> Software Updates -> Download Grid Applications' +from the workbench's menu bar. This option requires an application GUI server to +be available on the Grid (if no server has been found, the option is not +available). The job editor holds several tabs. First the application specific +tabs are shown for setting parameters in a user friendly way. + +In addition, the editor holds three generic panels: + +- The 'Files' panel highlight:4[]: This panel can be used to define file imports +from remote locations or preceding activities in a workflow. The application +specific panels usually only allow for defining imports from the local file +system. File exports to remote locations can also be set up here. + +- The 'Variables' panel highlight:5[]: This panel can be used to set the +application's input parameters directly (circumventing the application specific +panels that usually operate on these parameters, too. All parameters are passed +to the application via environment variables. Furthermore, the panel allows for +setting up additional environment variables for your application run. + +- The 'Resources' panel highlight:6[]: This panel can be used for specifying +resource requirements of the job, like the number of CPUs needed for a +calculation or the amount of memory. The tree-like view on the Grid to the right +serves for changing the selected target system for job execution. Note that the +list of suitable target systems is updated when changing resource requirements. +Also note that the boundaries for resource requirements change when a different +target system is selected. The selection can be undone by choosing a node that +is not a computational resource (e.g. the 'Grid' node or a registry node). + + +When all parameters are set, click the green 'submit' button (see highlight:7[] +in <<FIGURE_JOB_SUBMISSION>>) to submit the job to the selected target system. + +An additional action in the tool bar of the job editor is used to set the job's +lifetime highlight:8[]. When the job has reached the end of its lifetime, the +job resource representing the submitted job is destroyed and its working +directory is cleaned up automatically. This implies that the job's outcomes +cannot be accessed hereafter. +The default lifetime for jobs is set to 720 hours (30 days). + +[[SUBSUBSECTION_JOB_MONITORING]] +Monitoring Mode +^^^^^^^^^^^^^^^ + +As soon as a job is being submitted, the job file is copied into a newly created +subfolder of the `submitted' folder in the job project. The subfolder's name +consists of the String `submitted at', followed by a timestamp, e.g. `2010-03-29 +16-00-34' that indicates when the job was submitted (highlight:1[] in +<<FIGURE_JOB_OUTCOMES>>). This way, a history of all submitted versions of the +job is kept and the user can later look up old job descriptions and compare the +results of the associated job executions. +The copied version of the job file is then opened in a new job editor. + +[[FIGURE_JOB_OUTCOMES]] +.Job monitoring and fetching job outcomes +image::images/job_outcomes.png[{imagewidth?width="{imagewidth}"}] + +In order to inform the user about the execution state of the job, the editor is +put into 'monitoring mode'. This means that the job description cannot be edited +anymore and the title of the job editor indicates the current execution status +highlight:2[]. The status may be one of the four values 'submitting', 'running', +'finished', and 'failed'. If the job editor is closed in state 'submitting' the +job submission cannot be performed successfully and the subfolder with the copy +of the job file is deleted automatically. If the editor is closed in +state'running', execution of the job will continue normally on the server side. +By double-clicking the job file copy in the 'Navigator' view, the job editor +will be re-opened in monitoring mode and continue to watch the job execution. +Jobs can be aborted by selecting the `abort' item in their context menu. +Aborting a job will interrupt the execution of the associated application as +soon as possible (this depends on the target system's ability to abort +application runs), but leave the job node (and its working directory node) +accessible in the Grid Browser. In contrast, destroying a job will first abort +the job and then clean up all used resources including the job's working +directory. + + +[[SUBSUBSECTION_JOB_OUTCOME_VIEW]] +Fetching Job Outcomes +^^^^^^^^^^^^^^^^^^^^^ + +Once the job has finished successfully, the 'fetch output files' action becomes +available in the tool bar of the job editor in monitoring mode highlight:3[]. +After clicking it, a dialog will appear that shows all produced output files and +allows you to deselect files you do not want to download. After clicking 'OK' +the selected files are downloaded to the `output files' directory in the +subfolder that contains the copy of the submitted job highlight:4[]. Finally, a +new application specific 'Job Outcome' view will appear showing the contents of +the job's output files highlight:5[]. In our example a simple text editor shows +the output of the script, but more advanced visualisation software is used for +displaying the results of scientific applications (e.g. 3D molecule +visualisations for chemical applications). Alternatively, job outcomes can be +fetched by selecting 'fetch output files' from the context menu of job nodes in +the 'Grid Browser' view highlight:6[]. + + +[[SUBSECTION_WORKFLOW_EDITOR]] +The Workflow editor +~~~~~~~~~~~~~~~~~~~ + +This software component provides a graphical editing tool for workflows, +offering features like copy & paste, undoing changes, performing automatic graph +layouts, zooming, and printing of diagrams. Each workflow is created in its own +project and can be submitted and monitored like a single job. + + +[[SUBSUBSECTION_WORKFLOW_PROJECT_CREATION]] +Creating a workflow project +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In order to create a new workflow project, either select 'File -> New -> +Workflow Project' from the workbench's menu bar or select 'New -> Workflow +Project' from the context menu of the Navigator view (see +<<FIGURE_CREATE_PROJECT>>). After providing a valid name for both the parent +folder and the workflow file, the project is created. + + +[[SUBSUBSECTION_WORKFFLOW_EDITING]] +Editing mode +^^^^^^^^^^^^ + +When creating a new workflow project or opening an existing workflow file, a new +workflow editor instance is opened for setting up the workflow description (see +<<FIGURE_WFEDITOR_EDITING>>). + +[[FIGURE_WFEDITOR_EDITING]] +.The workflow editor: editing mode +image::images/workflow_editor.png[{imagewidth?width="{imagewidth}"}] + +Workflow descriptions are graphs consisting of nodes (commonly called activities +in workflow terminology) and edges (called transitions). When a workflow diagram +is created, it only displays a single activity: the starting activity of the +workflow highlight:1[]. Execution of the workflow begins at this activity. In +order to add new elements to the workflow, select them from the palette on the +left hand side and click in the diagram where you want to place them. Currently, +the palette offers the following elements that can be added to the workflow: + +. Application activities + +These activities represent jobs that are submitted to target systems during +workflow execution in order to run specific applications there. For each +application <<GUI,GUI>> that is installed in the client platform, the palette +shows a small icon and the name of the application highlight:2[]. By selecting +an icon and left-clicking a free spot within the workflow editor, a new activity +for the associated application will be created. This leads to the creation of a +job file in the `jobs' directory of the workflow project as soon as the workflow +is saved. When being double-clicked, application activities will open the job +editor for the associated job file. The editor can be used in order to change +the job description. When a job is embedded in a workflow, there are a several +additional possiblities for specifying the job's inputs and outputs that are not +available for single jobs: + +- Additions to the 'Files' panel: A File can now be exported as a 'Workflow +file' meaning that the file will be stored on some global storage and will be +available to subsequent workflow activities. +- Additions to the 'Variables' panel: This panel can be used to set the +application's input parameters to the values of workflow variables. Workflow +variables can be declared by special activities and modified while the workflow +is executed. Their current value during workflow execution is maintained by the +workflow engine and may be fed into a job's description before the job is +submitted. This mechanism allows for running the same job multiple times, with +different parameter values e.g. for performing parameter sweeps. +- Additions to the 'Resources' panel: Workflow jobs do not require users to +select a single target system for job execution. This is due to the fact that +the workflow engine has a resource broker which is capable of distributing jobs +to suitable target systems. In this process, specified resource requirements of +the job (e.g. amount of memory) are compared to the target systems' offerings +for finding a computing resource that fulfils the requirements. This is +generally referred to as `match-making'. In order to narrow down the choice of +target systems used for match-making, the user may select one or more target +systems as `candidate resources' for the job. Again, the selection can be undone +by choosing a node that is not a computational resource (e.g. the 'Grid' node or +a registry node). + +. Transitions + +Transitions represent the flow of control that passes from one activity to the +next. Currently, there are two types of transitions: unconditional highlight:3[] +and conditional highlight:4[] ones. Only unconditional transitions can be added +to the workflow manually. Conditional transitions are used in If-statements and +While-loops and are added automatically. The reason for this is that conditional +transitions may require a different joining behaviour: the default joining +behaviour when an activity has multiple incoming transitions is called +`synchronisation'. This means that the activity is only processed when all +incoming transitions have been processed. As you might imagine, this behaviour +is no longer appropriate when conditional transitions are used: the activity +that joins the if and else branches of an If-statement would never be processed +if it waited for both branches to finish. In order to hide this complexity from +users that are unfamiliar with workflow processing and programming languages, +If-statements and similar constructs will be modelled as sub-workflows that +automatically define the appropriate joining behaviour. +. Workflow structures + +Workflow structures are subgraphs that bring their own semantics on how to +process their child nodes. Currently, four workflow structures are provided: +groups, If-statements, While-loops, and ForEach-Loops highlight:5[]. +.. Groups are the simplest of all subgraphs. They are just containers for other +activities. Their content may be hidden by clicking the small minus symbol at +their top. +.. If-Statements influence the flow of control and contain two additional +subgraphs (which are modelled as groups): the if-branch and the else-branch. The +if-branch is processed when a certain user-defined condition holds. If the +condition evaluates to false the else-branch is processed instead. Both branches +can contain arbitrary activities and transitions, thus permitting nesting of +workflow structures. Conditions can be altered by double clicking the +conditional transition. This will open up the 'Properties' view which displays +relevant properties of workflow elements highlight:6[]. Most properties can be +modified through this view. There are currently two types of conditions: the +first type compares the exit status of an application to a value provided by the +user and the second one compares the value of a workflow variable to a +user-given value. +.. The While-loop provides a single subgraph called the loop-body that can be +processed multiple times (as long as the loop's condition holds true). The +While-loop declares a workflow variable that reflects the current number of loop +iterations, the so-called loop `iterator'. It also declares a variable modifier +that increments the loop iterator. The variable declaration can be changed in +the Properties view of the red activity at the top of the loop and the variable +modifier can be set up in the Properties view of the associated modifier +activity (at the bottom of the while loop). +.. ForEach-Loops can be used in order to create many similar jobs without having +to set up each job individually. They have two different modes of operation. The +first mode will iterate over a set of workflow variable values and run the +job(s) contained in the loop body once for each value in the set. The workflow +variable values can be used as input parameters for these jobs. Complex +parameter sweeps are possible, as multiple workflow variables can be sweeped at +the same time. The second mode is used to iterate over a set of files. The file +set may consist of any combination of local, remote or workflow files. This mode +provides a convenient way to process many different files simultaneously. The +operational mode and the parameters to the selected mode can be modified in the +Properties view of the orange activity at the top of the ForEach-loop. +The iterations of the ForEach-loop are usually executed in parallel. However, +there is an upper bound of parallel iterations which results from the workflow +engine's capabilities. There is also a way to lower this boundary by providing +an Integer value for the 'Number of parallel tasks' in the Properties view of +the ForEach activity. Setting this value to `1' will lead to sequential +execution of the loop iterations. + +. Variable declarations and modifiers highlight:7[] + +Additional workflow variables can be declared using the appropriate +'Declaration' activity. The Properties view of this activity allows for +(re-)naming the variable and assigning it a type (e.g. 'String' or 'Integer') +and initial value. A 'Modifier' activity can be used to change the value of a +workflow variable later. + + +When the user is pleased with the workflow description, the workflow can be +submitted via the editor's context menu highlight:8[] or the workbench's tool +bar. It can also be exported to an <<XML,XML>> based workflow language that the +workflow engine understands highlight:9[]. The exported workflow can later be +submitted to the workflow engine by the UNICORE commandline client. This feature +is useful e.g. in order to make predefined workflows available via a web +interface (the Chemomentum web portal solution uses the commandline client for +workflow submission). + + +[[SUBSUBSECTION_WORKFLOW_MONITORING]] +Monitoring mode +^^^^^^^^^^^^^^^ + +The workflow editor is also used for monitoring the execution of workflows, so +the basic graphical representation of a workflow stays the same before and after +submission to the workflow engine (see <<FIGURE_WFEDITOR_MONITORING>>). This +helps in identifying which part of the workflow is being executed at a given +point in time. + +[[FIGURE_WFEDITOR_MONITORING]] +.The workflow editor: monitoring mode and the Trace Graph view +image::images/monitoring_tracing.png[{imagewidth?width="{imagewidth}"}] + +When a workflow has been submitted, a new folder is created in the `submitted' +subfolder of the workflow project. This folder contains a copy of the workflow +file that is automatically opened in a new workflow editor panel - in monitoring +mode. In this mode, the editor disallows any changes to the workflow. It +displays the progress of workflow execution by adding small icons to the nodes +of the workflow graph that symbolise the execution state of these parts +highlight:1[]. + +Outcomes of jobs can be fetched as soon as the jobs have finished. This function +is available via the context menu of application activities and the 'fetch +output files' action in the global tool bar (after selecting the activity for +which to fetch outcomes). Job outcomes are downloaded to the `output files' +folder again, so they can easily be found later and associated with the workflow +by which they were produced. Monitoring a workflow can be interrupted by simply +closing the editor panel highlight:2[]. By double-clicking the file that +represents the submitted workflow (in the 'Navigator' view), the editor panel +will be re-opened and continue to monitor the execution of the workflow. + + +[[SUBSUBSECTION_TRACE_GRAPH_VIEW]] +The Trace Graph view +^^^^^^^^^^^^^^^^^^^^ + +In addition to monitoring the execution states of activities in the workflow, +the user may trace the workflow for finding out where his jobs were submitted. +This action is available via the context menu of the workflow editor. A trace +graph will open, showing all messages that were sent by the workflow system +during the execution of the workflow highlight:3[]. By hovering the mouse over a +node or edge in the trace graph, additional information about the element is +displayed in a tooltip. The set of traced messages can be updated by clicking +the 'Refresh' button in the tool bar of the 'Trace Graph' view highlight:4[]. +Additional buttons allow to zoom in and out (zooming can also be achieved by +rotating the mouse wheel while pressing the `control' key). + + +[[SUBSECTION_INTERACTIVE_SITE_ACCESS]] +Interactive site access +~~~~~~~~~~~~~~~~~~~~~~~ + +The UNICORE Rich Client features a Terminal view which can be used to log on +to remote hosts via SSH and GSISSH. It complies to the VT100 standard for terminal +emulation and can hold multiple terminal sessions (in multiple tabs). Sessions +can be created via the 'open terminal' action from the context menu of a target +system node. Please note, that this action is only available, if the +administrator of the UNICORE site has enabled interactive access and provided +necessary information about the target system, i.e. the host name and port that +should be used for establishing the interactive connection and the available +connection methods. Currently, the UNICORE Rich Client provides two different +secure connection methods, Plain SSH and GSISSH. Apart from that, additional +protocols can be used in the future -- both UNICORE client and server are +extensible in this regard. + +[[SUBSUBSECTION_PLAIN_SSH_PROVIDER]] +Plain SSH +^^^^^^^^^ +When connecting to an SSH server via plain (i.e. conventional) SSH, the user can +choose between three different authentication methods : + +- Password +- Keyboard-Interactive +- Public-key: If the user's private key path wasn't specified before, the +UNICORE Rich Client tries to find the key in the appropriate default directory +(e.g. ~/.ssh/id_dsa). If this fails the user is prompted to specify the path. +In case your private key format is not recognized properly, please read +<<SUBSUBSECTION_INVALID_KEY_FOR_SSH>>. + +[[SUBSUBSECTION_GSISSH_PROVIDER]] +GSISSH +^^^^^^ +The GSISSH connection method provides access to GSISSH servers via RFC-3820 +compliant proxy certificates. The proxy is created from the keystore of the +UNICORE Client when the user starts to connect to the server. It can be +stored on the local machine if required. It is possible to choose between +different aliases representing different keys in the keystore, different +delegation types, and different proxy types. Furthermore, the lifetime of the +proxy certificate can be set (the default is 12 hours). +When connecting to GSISSH servers the UNICORE Rich Client converts the PEM +formatted CA certificates in the UNICORE client's truststore to GSISSH-conform +certificates, and stores them on the local machine. By default these files are ... [truncated message content] |