********************************************************************************************
1. How to use the GUI based iShare

***** STEP 1.  Start the P2P node. 

Go to the menu "System===> P2P client", and click "start". You don't need to change
the P2P configuration unless you want to start a new P2P ring (this case, you could
manage a group sharing resources privately).


***** STEP 2. View the published resource.

Go to one specific directory listed on the left side of the split window, e.g. 
"Computer Engineering//compiler//program", then click the menu "Resource ===> Discover In(P2P)".
All the resources published as "program" under the "compiler" direcotry will show up.
Repeat the discovery, instances (executables with specific versions and providers) will 
be discovered and listed for each application. For example, if the user discovers at 
"polaris", an instance "longmorn.ecn.purdue.edu:6.0" will be found, which means the version 
number of this polaris is 6.0 and it could be run on the machine named "longmorn.ecn.purdue.edu". 


***** STEP 3. Run an application.

Users could run the discovered tools remotely through SSH or extended RMI(IRMI) 
now. Go to an application INSTANCE (e.g. the items under the "polaris" directory) 
listed in the resource directory, click the right mouse button (or the menu "Run" and 
choose the "iRun" menu item. If it's the first time to run the application, iShare 
will ask for the required access information to the remote program. If this 
succeeds, a dialog will pop up on which users could specify parameters  
and in/output options for the execution. 

If the application instance is an unpinned service (with no fixed host machine), the 
executioin may FAIL due to the unavailability of matched machine resources. In this case,
you could try later when such a machine is available again or newly published.
 

***** STEP 4. Publish your own resource.

Publishing resources needs two steps. At first, go to the menu "Resource ===> Create Descriptor",
choose the resource type you want to publish, provide detailed information 
for the resource through the interactive tool and finally save the information to 
a file(*.RDF). A new RDF file will be created. Read the next section for detailed
instructions for creating a RDF descriptor. The second step is to publish the resource
with P2P protocols, going to the menu "Resource ===> Publish Descriptor" and choosing 
the descriptor you want to publish.

If there's something wrong when creating the RDF file, error messages will pop up
in the status window at the bottom of the iShare main window. And make sure you input
all the necessary information in the required format when creating the descriptor.

If you publish a machine resource and want to other users to execute applications
on it through IRMI, you need to start the IRMI server on the machine. Go to the menu
"System ===> RMI Server" and start it.

TIPS FOR PUBLISHING APPLICATIONS:
 1) For an application run through RMI, never define "PATH" as an environment
 2) When an application definition is updated, the backend RMI server may need to restart
 3) Currently, three application interfaces are supported: batch, command-line interactive
    and graphic interface. The interactive interfaces are supported with VNC. 
********************************************************************************************

2. How to use the interactive tool to create RDF descriptors

**** 2.1. The RDF descriptor for a program

   **2.1.1 Provider
	The publisher needs to input the contact information here. There's no fixed format
        for the "Organization". The "project Home Page" should be a URL that end users could
        access to know more about the published program.
 
   **2.1.2 Attributes
	
	$$$$ Enlarge the window if some information at the bottom is hidden.

      *2.1.2.1 Excutable's name	
	The publisher needs to input enough information for "Executable's name", so that no 
	pre-knowledge about the program is needed. For example, if the program is a java 
	program named "HelloWorld", the "Executable's name" should be 
	"java (-cp ../lib/*.jar) HelloWorld". 

      *2.1.2.2 Categories of the Program
	The publisher could choose the existing "MainLab" and choose or add "Lab" in which
	the program should reside. 	

      *2.1.2.3 1-line description
	Input a short description for this program, e.g. the functionality. 

      *2.1.2.4 URL of the man page
	A URL where end-users could find the detailed "man page" for the published program.	

   **2.1.3 Access
      *2.1.3.1 Export operations
	Three types of operations are supported: the program could be executed on a host
	machine (Execution Server) directly; the program could be only downloaded and run
	on a certain machine as the result of resource allocation; or the combination of 
	these two cases.	

      *2.1.3.2 Execution Authentication		
	If the program could be run on a dedicated execution server, then authentication
	information is required. Currently, two authentication protocols are supported:
	the standard SSH and RMI (in this case, the dedicated server should already start
	a RMI server through iShare). For both these two protocols, the UNIX backend is
	recommended.

   **2.1.4 Hardware Support
	If the program could be downloaded and then installed instantaneously on a machine,
	information for platform requirements is needed. Here, it assumes that the program
	is self-supported, i.e. all the required software libraries/tools are already included
	in the installation package of the program.

   **2.1.5 Arguments
	Arguments are command-line options to run the program through Unix Shell. The information
	to describe one argument includes, semantics (Short description), argument types (Type
	of the arguments), value ranges, options or formats (Possible values), flag and whether
	the argument is optional (check box of "The argument must be provided").
	If there're multiple arguments, click the "Save and new" button at the bottom to start
	adding a new argument. 
		
   **2.1.6 Environment Variables
	If some environment variables need to be set (e.g. for an instaneously installed program),
	the publisher could specify the name and value for each environment variable. 

   After all the above steps, the publisher could save all the input information into a RDF file
   by clicking the "save" button at the bottom of the dialog. Make sure that the file has a suffix
   of ".rdf". The file could be saved anywhere on the local disk. 

**** 2.2. The RDF descriptor for a machine

   **2.2.1 Identity
	The name of the published machine should be the full name, e.g. "min.ecn.purdue.edu".  
	
   **2.2.3 Attributes
	The publisher could choose the lab(s) to which the published machine belongs. It 
	means the machine is implicitly dedicated to these labs and satisfy the platform 
	requirements of most applications published to the labs. 
	
   **2.2.4 Access 
	The authentication information specifies which protocol (SSH or RMI) will be used
	to run jobs on this published machine. "Derectory to install embedded services" 
	means the directory where a downloaded program could be installed on this machine.
	The installation probably consumes a large amount of disk space.

********************************************************************************************
3. Warning

Running tools through the extended RMI is still under test. Users are encouraged to 
publish tools that could be executed through RMI. This will do NO damage to your
system at all. Severe bugs may crash iShare, but not causing any security problems to 
the host machine.