author: Christian Loeschen
email: christian.loeschen@tu-dresden.de



TOC:

I	Add stellaris module to irods
II	Using stellaris module
III	Using the module for rdf creation



I	Add stellaris module to irods:
	
	1. Copy the stellaris module into <irods_path>/modules
	2. Ensure that in info.txt the line Enabled is set to: yes
	3. The raptor (redland rdf) & curl libraries have to be available 
	4. Compile irods
	5. Add the following lines to <irods_path>/server/config/reConfigs/core.irb:
		
		#	stellaris rules
		#	simple module test rule
		acStellarisModuleTest||msiStellarisTest|nop
		
		#	rule adds rdf-graph for test purpose to stellaris, but not to irods
		acStellarisConnectionTest(*SUB,*PRED,*OBJ,*RDF_REP,*OUT)||msiStellarisCreateRdf(*SUB,*PRED,*OBJ,*RDF_REP,*GRAPH)##msiStellarisSendToStellaris(*SUB,*GRAPH,*RETCODE,*OUT)|nop
		
		#	rule for creating a rdf-graph and adding to stellaris and irods
		acStellarisAddRdf(*SUB,*PRED,*OBJ,*RDF_REP,*OUT)||msiStellarisCreateRdf(*SUB,*PRED,*OBJ,*RDF_REP,*GRAPH)##msiStellarisSendToStellaris(*SUB,*GRAPH,*RETCODE,*OUT)##ifExec(*RETCODE == 201,msiStellarisAddMetadata(*SUB,*RDF_REP,*GRAPH,*RETCODE),nop,nop,nop)|nop
		
	6. Add a file mod_stellaris.properties to <irods path>/server/config/
	   Example of mod_stellaris.properties:
		
		#necessary:
		stellaris-url:https://stellaris-url.org:9090
		url_graph_prefix:irods://my-domain.org
		
		#used for certificate authentication on stellaris in secure mode:
		x509-cert-file:/path/to/servercert.pem
		x509-key-file:/path/to/serverkey.pem
		
		#used when verifying peer certificate is needed:
		cacert-file:/path/to/cacert.pem
		
		#only when a proxy is used:
		#proxy:myproxy:port
		
	   Ensure that irods has rights necessary to read the files.
	
II	Using stellaris module:
	
	To work with the stellaris module you have to use the irule icommand. The 
	icommands can be found in <irods_path>/clients/icommands/bin/. All the rules 
	used in the following tasks can be found in the stellaris_rules	directory. 
	
	You can check whether stellaris module is integrated properly using the 
	stellaris test microservice. Run the test using
	
		christian@linux-s0n6:<irods_path>/clients/icommands/bin> ./irule \
		--test -F <irods_path>/modules/stellaris/stellaris_rules/test1.ir
	
	The output has to look similar to this:
	
		Enter your current iRODS password:
		Level 0: NOTICE: +Testing Rule Number:1000 for Action:acStellarisModuleTest
		Level 1: NOTICE: ...Performing Function:msiStellarisTest
		Level 2: NOTICE:     msiStellarisTest test log
	
	You can test the connectivity to stellaris using the following command:
	
		christian@linux-s0n6:<irods_path>/clients/icommands/bin> ./irule \
		-v -F <irods_path>/modules/stellaris/stellaris_rules/test2.ir
	
	This should be the output:
	
		Enter your current iRODS password:
		rcExecMyRule: acStellarisConnectionTest(*SUB,*PRED,*OBJ,*RDF_REP,*OUT)
		outParamDesc: *OUT
		ExecMyRule completed successfully.    Output
		
		  output index: 0
		    label: *OUT
		    type: STR_PI
		    str content: response code: 201
    
    201 is the return code when everything went well. On success a graph is 
    created on stellaris: 
    
		christian@linux-s0n6:~> stellaris-client --recursive collection list /
		Sub-collections:
		/my/
		/my/test/
		
		Graphs:
		/my/test/subject
		christian@linux-s0n6:~> stellaris-client graph retrieve /my/test/subject
		<?xml version="1.0" encoding="UTF-8"?>
		<rdf:RDF
		   xmlns:ns0="http://my.test/namespace#"
		   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
		>
		  <rdf:Description rdf:about="irods://my-domain.org/my/test/subject">
		    <ns0:predicate>my_test_object</ns0:predicate>
		  </rdf:Description>
		</rdf:RDF>
		christian@linux-s0n6:~> stellaris-client graph delete /my/test/subject    
	
	If all that went well, the stellaris module seems to be configured properly. 
	Now you can use one of the following methods to create rdf graphs, add them 
	to stellaris and store it as metadata on irods.
	
	1. Use without an .ir file:
	
		christian@linux-s0n6:<irods_path>/clients/icommands/bin> ./irule -v \
		"acStellarisAddRdf(*SUB,*PRED,*OBJ,*RDF_REP,*OUT)" \
		"*SUB=/my/test/subject%*PRED=http://my.test/namespace#predicate%*OBJ=my_test_object%*RDF_REP=rdfxml" \
		"*OUT"
		
	2. Use with an .ir file and wildcards:
	
		christian@linux-s0n6:<irods_path>/clients/icommands/bin> ./irule -v \
		-F <irods_path>/modules/stellaris/stellaris_rules/stellarisAddRdf.ir \
		/my/test/subject http://my.test/namespace#predicate my_test_object 
		
	   Arguments given on command line are inserted in the same order as they 
	   occure in the .ir file.
	
	3. Use with an .ir file that contains all necessary data:
	
		christian@linux-s0n6:<irods_path>/clients/icommands/bin> ./irule -v \
		-F /path/to/myStellarisAddRdf.ir
		
	   In this case myStellarisAddRdf.ir should contain three lines: 
	
		acStellarisAddRdf(*SUB,*PRED,*OBJ,*RDF_REP,*OUT)
		*SUB=/my/test/subject%*PRED=http://my.test/namespace#predicate%*OBJ=my_test_object%*RDF_REP=rdfxml
		*OUT
		
	It's also possible to mix the 2nd and 3rd method with some fix arguments 
	in the .ir file and some variable arguments to input on command line.
	
	You can use the imeta icommand to see the metadata on irods:
	
		christian@linux-s0n6:<irods_path>/clients/icommands/bin> ./imeta \
		ls -d /my/test/subject
		Enter your current iRODS password:
		AVUs defined for dataObj /my/test/subject:
		attribute: rdfxml
		value: <?xml version="1.0" encoding="utf-8"?>
		<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
		  <rdf:Description rdf:about="irods://my-domain.org/my/test/subject">
		    <ns0:predicate xmlns:ns0="http://my.test/namespace#">my_test_object</ns0:predicate>
		  </rdf:Description>
		</rdf:RDF>
		
		units: 201
		
	If you use a .ir file where there are set some values to the variables, 
	you	can also mix it with arguments set on command line. Then, the values 
	set in the file are treated as default values that are replaced by 
	command line arguments.
	
	The rdf graph is stored as value for the attribute rdfxml. As unit is 
	stored the stellaris return code for the creation of the rdf graph. 201 
	is the return code on success. This is only to verify the correct creation 
	on stellaris.
	
	NOTE: When creation of the rdf graph on stellaris fails, there also won't 
	be 	stored any metadata on irods. In this case the irule command will 
	return a message with the error and the stellaris error code.
	
	NOTE: The SUB parameter must be an existing file in irods. Otherwise irods 
	can't store any metadata with it and the execution of the rule will	fail. 
	This will cause inconsistency, because the graph on stellaris is already 
	created.
	
	NOTE: The behaviour of the irule command described here (based on irods 1.1) 
	can not be guaranteed, since irule behaviour can be changed by the irods 
	developers every time.
	
III	Using the module for rdf graph creation:
	
	The microservice for the creation of rdf graphs is:
	msiStellarisCreateRdf(*SUB,*PRED,*OBJ,*RDF_REP,*GRAPH)
	
	SUB, PRED and OBJ are the corresponding values for rdf.
	
	There are different rdf serializers available with the redland rdf 
	libraries. RDF_REP is the name of the serializer to use. An explanation 
	of the different serializers can be found at the librdf sites: 
	http://librdf.org/raptor/api/raptor-serializers.html
	
	These values must be given as input parameters. GRAPH is the output 
	parameter and it contains the created rdf graph. A simple example of 
	the usage can be found in 
	<irods_path>/modules/stellaris/stellaris_rules/test3.ir. It is easy 
	to try out using the irule command:
	 
		christian@linux-s0n6:<irods_path>/clients/icommands/bin> ./irule -v \
		-F <irods_path>/modules/stellaris/stellaris_rules/test3.ir
		Enter your current iRODS password:
		rcExecMyRule: msiStellarisCreateRdf(*SUB,*PRED,*OBJ,*RDF_REP,*GRAPH)
		outParamDesc: *GRAPH
		ExecMyRule completed successfully.    Output
		
		  output index: 0
		    label: *GRAPH
		    type: STR_PI
		    str content: <?xml version="1.0" encoding="utf-8"?>
		<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
		  <rdf:Description rdf:about="irods://my-domain.org/my/test/subject">
		    <ns0:predicate xmlns:ns0="http://my.test/namespace#">my_test_object</ns0:predicate>
		  </rdf:Description>
		</rdf:RDF>
	
	If the module is used for rdf graph creation only, it is not necessary to 
	make the configuration in I.6. Only if an additional prefix for the subject 
	is needed, url_graph_prefix must be set.