wf4ever-rosrs-client 0.1.1

data/.rvmrc

@@ -0,0 +1 @@
+rvm --create use 1.9.3@rosrs_client

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+
+gem "json"
+gem "rdf"
+gem "rdf-raptor"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "rdoc", "~> 3.12"
+  gem "bundler", "~> 1.2.1"
+  gem "jeweler", "~> 1.8.4"
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Finn Bacall
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,180 @@
+ROSRSClient
+=================
+
+Partial port of Python ROSRS_Session code to Ruby.
+
+[This project [8]][ref8] is intended to provide a Ruby-callable API for [myExperiment [9]][ref9] to access [Research Objects [1]][ref1], [[2]][ref2] stored in RODL, using the [ROSRS API [3]][ref3].  The functions provided closely follow the ROSRS API specification.  The code is based on an implementation in Python used by the RO_Manager utility; a full implementat ROSRS test suite can be found in the [GitHub `wf4ever/ro-manager` project [7]][ref7].
+
+[ref1]: http://www.wf4ever-project.org/wiki/pages/viewpage.action?pageId=2065079 "What is an RO?"
+
+[ref2]: http://wf4ever.github.com/ro/ "Wf4Ever Research Object Model"
+
+[ref3]: http://www.wf4ever-project.org/wiki/display/docs/RO+SRS+interface+6 "ROSRS interface (v6)"
+
+[ref7]: https://github.com/wf4ever/ro-manager/blob/master/src/rocommand/ROSRS_Session.py "Python ROSRS_Session in RO Manager.  See also test suite: https://github.com/wf4ever/ro-manager/blob/master/src/rocommand/test/TestROSRS_Session.py"
+ 
+[ref8]: https://github.com/gklyne/ruby-http-session "ruby-http-session project, or successor"
+
+[ref9]: http://www.myexperiment.org/ "De Roure, D., Goble, C. and Stevens, R. (2009) The Design and Realisation of the myExperiment Virtual Research Environment for Social Sharing of Workflows. Future Generation Computer Systems 25, pp. 561-567. doi:10.1016/j.future.2008.06.010"
+
+
+## Contents
+
+* Contents
+* Package structure
+* API calling conventions
+* A simple example
+* Development setup
+* URIs
+* Further work
+* References
+
+
+## Package structure
+
+Key functions are currently contained in four files:
+
+* `lib/wf4ever/rosrs_session.rb`
+* `lib/wf4ever/rdf_graph.rb`
+* `lib/wf4ever/namespaces.rb`
+* `lib/wf4ever/folders.rb`
+* `test/test_rosrs_session`
+
+The main functions provided by this package are in `rosrs_session`.  This module provides a class whose instances manage a session with a specified ROSRS service endpoint.  A service URI is provided when an instance is created, and is used as a base URI for accessing ROs and other resources using relative URI references.  Any attempt to access a resource on a different host or post is rejected.
+
+`rdf_graph` implements a simplified interface to the [Ruby RDF library [4]][ref4], handling parsing of RDF from strings, serialization to strings and simplified search and access to individual triples.  Most of the functions provided are quite trivial; the module is intended to provide (a) a distillation of knowledge about how to perform desired functions using the RDF and associated libraries, and (b) a shim layer for adapting between different conventions used by the RDF libraries and the `rosrs_session` library.  The [Raptor library [5]][ref5] and its [Ruby RDF interface[6]][ref6] are used for RDF/XML parsing and serialization.
+
+[ref4]: http://rdf.rubyforge.org/ "RDF.rb: Linked Data for Ruby"
+
+[ref5]: http://librdf.org/raptor/ "Raptor RDF Syntax Library"
+
+[ref6]: http://rdf.rubyforge.org/raptor/ "Raptor RDF Parser Plugin for RDF.rb"
+
+`namespaces` provides definitions of URIs for namespaces and namespace terms used in RDF graphs.  These are in similar form to the namespaces provided by the RDF library.
+
+`folders` contains objects to represent and traverse RO's folder structure.
+
+`test_rosrs_session` is a test suite for all the above.  It serves to provide regression testing for implemented functions, and also to provide examples of how the various ROSRS API functions provided can be accessed.
+
+
+## API calling conventions
+
+Many API functions have a small number of mandatory parameters which are provided as normal positional parameters, and a (possibly larger) number of optional keyword parameters that are provided as a Ruby hash.  The Ruby calling convention of collecting multiple `key => value` parameter expressions into a single has is used.
+
+Return values are generally in the form of an array, which can be used with parallel assignment for easy access to the return values.
+
+Example:
+
+    code, reason, headers, body = rosrs.do_request("POST", rouri,
+        :body   => data
+        :ctype  => "text/plain"
+        :accept => "application/rdf+xml"
+        :headers    => reqheaders)
+
+
+## A simple example
+
+Here is a flavour of how the `rosrs_session` module may be used:
+
+    # Create an ROSRS session
+    rosrs = ROSRSSession.new(
+        "http://sandbox.wf4ever-project.org/rodl/ROs/", 
+        "47d5423c-b507-4e1c-8")
+
+    # Create a new RO
+    code, reason, rouri, manifest = @rosrs.create_research_object("Test-RO-name")
+    if code != 201
+        raise "Failed to create new RO: "+reason
+    end
+
+    # Aggregate a resource into the new RO
+    res_body = %q(
+        New resource body
+        )
+    options = { :body => res_body, :ctype => "text/plain" }
+
+    # Create and aggregate "internal" resource in new RO
+    code, reason, proxyuri, resourceuri = rosrs.aggregate_internal_resource(
+        rouri, "data/test_resource",
+        :body => res_body,
+        :ctype => "text/plain")
+    if code != 201
+        raise "Failed to create new resource: "+reason
+
+    # Create a new folder
+    folder_contents = [{:name => 'test_data.txt', :uri => 'http://www.example.com/ro/file1.txt'},
+                       {:uri => 'http://www.myexperiment.org/workflows/7'}]
+    folder_uri = rosrs.create_folder(rouri, "Input Data", folder_contents).uri
+
+    # Examine a folder
+    folder = rosrs.get_folder(folder_uri)
+    puts folder.name
+    puts folder.contents.inspect
+
+
+
+
+    # When finished, close session
+    rosrs.close
+
+
+## Development setup
+
+Development has been performed using Ruby 1.8.7 on Ubuntu Linux 10.04 and 12.04.  The code uses `rubygems`, `json`, `rdf` and `rdf-raptor` libraries beyond the standard Ruby libraries.
+
+The `rdf-raptor` Ruby library uses the Ubuntu `raptor-util` and `libraptor-dev` packages.  NOTE: the Ruby RDF documentation does not mention `libraptor-dev`, but I found that without this the RDF libraries would not work for parsing and serializing RDF/XML.
+
+Once the environment is set up, I find the following statements are sufficient include the required libraries:
+
+    require "wf4ever/rosrs_client"
+
+## URIs
+
+Be aware that the standard Ruby library provides a URI class, and that the RDF library provides a different, incompatible URI class:
+
+    # Standard Ruby library URI:
+    uri1 = URI("http://example.com/")
+    
+    # URI class used by RDF library:
+    uri2 = RDF::URI("http://example.com")
+
+These URIs are not equivalent, and are not even directly comparable.
+
+Currently, the HTTP handling code uses the standard Ruby library URIs, and the RDF handling code uses URIs provided by the RDF library.  The `namespaces` module returns `RDF::URI` values.
+
+I'm not currently sure if this will prove to cause problems.  Take care when dereferencing URIs obtained from RDF.
+
+## Further work
+
+At the time of writing this, the code is very much a work in progress.  Some of the things possibly yet to-do include:
+
+* Fork project into the wf4ever organization.  Rename to rosrs_session.
+* Complete the APi functions
+* Work out strategy for dealing with different URI classes.
+* When creating an RO, use the supplied RO information to create some initial annotations (similar to RO Manager)?
+* Refactor `rosrs_session.rb` to separate out `http_session`
+* May want to investigate "streaming" RDF data between HTTP and RDF libraries, or using RDF reader/writer classes, rather than transferring via strings.  Currently, I assume the RDF is small enough that this doesn't matter.
+* Refactor test suite per tested module (may require simple HTTP server setup if HTTP factored out as above)
+
+
+## References
+
+[[1] _What is an RO?_][ref1]; Wf4Ever Research Object description and notes.
+
+[[2] _Wf4Ever Research Object Model_][ref2]; Specification of RO model.
+
+[[3] _Wf4ever ROSRS interface (v6)_][ref3]; Description of the HTTP/REST interface for accessing and updating Research Objects, implemented by Wf4Ever RODL.
+
+[[4] `RDF.rb`][ref4]; Linked Data for Ruby
+
+[[5] _Raptor_][ref5]; Raptor RDF Syntax Library
+
+[[6] `rdf_raptor`][ref6]; Raptor RDF Parser Plugin for RDF.rb
+
+[[7] _Python ROSRS\_Session in RO Manager_][ref7];  See also the test suite: [TestROSRS_Session.py ](https://github.com/wf4ever/ro-manager/blob/master/src/rocommand/test/TestROSRS_Session.py).
+
+[[8] `ruby-http-session` project, or successor][ref8]
+
+[[9] _myExperiment_][ref9];  "De Roure, D., Goble, C. and Stevens, R. (2009) The Design and Realisation of the myExperiment Virtual Research Environment for Social Sharing of Workflows. Future Generation Computer Systems 25, pp. 561-567. doi:10.1016/j.future.2008.06.010"
+
+

data/Rakefile

@@ -0,0 +1,44 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "wf4ever-rosrs-client"
+  gem.homepage = "http://github.com/fbacall/rosrs_client"
+  gem.summary = %Q{A client to interact with the ROSRS API.}
+  gem.description = %Q{A port of the ROSRS API Python client into Ruby.}
+  gem.email = "finn.bacall@cs.man.ac.uk"
+  gem.authors = ["Graham Klyne","Finn Bacall"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "rosrs_client #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.1

data/lib/wf4ever/rosrs/annotation.rb

@@ -0,0 +1,76 @@
+module ROSRS
+  class Annotation
+
+    attr_reader :uri, :body_uri, :resource_uri, :created_at, :created_by, :research_object
+
+    def initialize(research_object, uri, body_uri, resource_uri, options = {})
+      @research_object = research_object
+      @session = @research_object.session
+      @uri = uri
+      @body_uri = body_uri
+      @resource_uri = resource_uri
+      @created_at = options[:created_at]
+      @created_by = options[:created_by]
+      @loaded = false
+      if options[:body]
+        @body = options[:body]
+        @loaded = true
+      end
+      load if options[:load]
+    end
+
+    ##
+    # The resource which this annotation relates to
+    def resource
+      @resource ||= @research_object.resources(@resource_uri) ||
+                    @research_object.folders(@resource_uri) ||
+                    ROSRS::Resource.new(@research_object, @resource_uri)
+    end
+
+    def loaded?
+      @loaded
+    end
+
+    def load
+      c,r,u,@body = @session.get_annotation(body_uri)
+      @loaded = true
+    end
+
+    def body
+      load unless loaded?
+      @body
+    end
+
+    def delete
+      code = @session.remove_annotation(uri)
+      @loaded = false
+      @research_object.remove_annotation(self)
+      code == 204
+    end
+
+    def self.create(ro, resource_uri, annotation)
+      if ROSRS::Helper.is_uri?(annotation)
+        code, reason, annotation_uri = ro.session.create_annotation_stub(ro.uri, resource_uri, annotation)
+        self.new(ro, annotation_uri, annotation, resource_uri)
+      else
+        code, reason, annotation_uri, body_uri = ro.session.create_internal_annotation(ro.uri, resource_uri, annotation)
+        self.new(ro, annotation_uri, body_uri, resource_uri, :body => annotation)
+      end
+    end
+
+    def update(resource_uri, annotation)
+      if ROSRS::Helper.is_uri?(annotation)
+        code, reason = @session.update_annotation_stub(@research_object.uri, @uri, resource_uri, body_uri)
+        @loaded = false
+      else
+        code, reason, body_uri = @session.update_internal_annotation(@research_object.uri, @uri, resource_uri, annotation)
+        @loaded = true
+        @body = annotation
+      end
+      @resource_uri = resource_uri
+      @body_uri = body_uri
+      self
+    end
+
+  end
+end

data/lib/wf4ever/rosrs/exceptions.rb

@@ -0,0 +1,19 @@
+  # Exception class used to signal HTTP Session errors
+  module ROSRS
+
+    class Exception < Exception
+    end
+
+    class NotFoundException < Exception
+    end
+
+    class ForbiddenException < Exception
+    end
+
+    class UnauthorizedException < Exception
+    end
+
+    class ConflictException < Exception
+    end
+
+  end

data/lib/wf4ever/rosrs/folder.rb

@@ -0,0 +1,127 @@
+module ROSRS
+
+  # A representation of a folder in a Research Object.
+  class Folder < Resource
+
+    attr_reader :name
+
+    ##
+    # +research_object+:: The Wf4Ever::ResearchObject that aggregates this folder.
+    # +uri+::             The URI for the resource referred to by the Folder.
+    # +options+::         A hash of options:
+    # [:contents_graph]   An RDFGraph of the folder contents, if on hand (to save having to make a request).
+    # [:root_folder]      A boolean flag to say if this folder is the root folder of the RO.
+    def initialize(research_object, uri, proxy_uri = nil, options = {})
+      super(research_object, uri, proxy_uri)
+      @name = uri.to_s.split('/').last
+      @session = research_object.session
+      @loaded = false
+      if options[:contents_graph]
+        @contents = parse_folder_description(options[:contents_graph])
+        @loaded = true
+      end
+      @root_folder = options[:root_folder]
+    end
+
+    ##
+    # Fetch the entry with name +child_name+ from the Folder's contents
+    def child(child_name)
+      contents.select {|child| child.name == child_name}.first
+    end
+
+    ##
+    # Returns boolean stating whether or not a description of this Folder's contents has been fetched and loaded.
+    def loaded?
+      @loaded
+    end
+
+    ##
+    # Returns whether or not this folder is the root folder of the RO
+    def root?
+      @root_folder
+    end
+
+    ##
+    # Returns an array of FolderEntry objects
+    def contents
+      load unless loaded?
+      @contents
+    end
+
+    ##
+    # Fetch and parse the Folder's description to get the Folder's contents.
+    def load
+      @contents = fetch_folder_contents
+      @loaded = true
+    end
+
+    ##
+    # Delete this folder from the RO. Contents will be preserved.
+    # Also deletes any entries in other folders pointing to this one.
+    def delete
+      code = @session.delete_folder(@uri)[0]
+      @loaded = false
+      @research_object.remove_folder(self)
+      code == 204
+    end
+
+    ##
+    # Add an entry to the folder. +resource+ can be a ROSRS::Resource object or a URI
+    def add(resource, entry_name = nil)
+      if resource.instance_of?(ROSRS::Resource)
+        contents << ROSRS::FolderEntry.create(self, entry_name, resource.uri)
+      else
+        contents << ROSRS::FolderEntry.create(self, entry_name, resource)
+      end
+
+    end
+
+    ##
+    # Remove an entry from the folder.
+    def remove(entry)
+      entry.delete
+      contents.delete(entry)
+    end
+
+    ##
+    # Create a folder in the RO and add it to this folder as a subfolder
+    def create_folder(name)
+      # Makes folder name parent/child instead of just child
+      folder_name = (URI(uri) + URI(name) - URI(@research_object.uri)).to_s
+      folder = @research_object.create_folder(folder_name)
+      add(folder.uri, name)
+      folder
+    end
+
+    def self.create(ro, name, contents = [])
+      code, reason, uri, proxy_uri, folder_description = ro.session.create_folder(ro.uri, name, contents)
+      self.new(ro, uri, proxy_uri, :contents_graph => folder_description)
+    end
+
+    private
+
+    # Get folder contents from remote resource map file
+    def fetch_folder_contents
+      code, reason, headers, uripath, graph = @session.get_folder(uri)
+      parse_folder_description(graph)
+    end
+
+    def parse_folder_description(graph)
+      contents = []
+
+      query = RDF::Query.new do
+        pattern [:folder_entry, RDF.type, RDF::RO.FolderEntry]
+        pattern [:folder_entry, RDF::RO.entryName, :name]
+        pattern [:folder_entry, RDF::ORE.proxyFor, :target]
+      end
+
+      # Create instances for each item.
+      graph.query(query).each do |result|
+        contents << ROSRS::FolderEntry.new(self, result.name.to_s, result.folder_entry.to_s, result.target.to_s)
+      end
+
+      contents
+    end
+
+  end
+end

data/lib/wf4ever/rosrs/folder_entry.rb

@@ -0,0 +1,44 @@
+module ROSRS
+
+  # An item within a folder.
+
+  class FolderEntry
+
+    attr_reader :parent_folder, :name, :uri
+
+    ##
+    # +parent_folder+:: The ROSRS::Folder object in which this entry resides..
+    # +name+::          The display name of the ROSRS::FolderEntry.
+    # +uri+::           The URI of this ROSRS::FolderEntry
+    # +resource_uri+::  The URI for the resource referred to by this ROSRS::FolderEntry.
+    def initialize(parent_folder, name, uri, resource_uri)
+      @uri = uri
+      @name = name
+      @resource_uri = resource_uri
+      @parent_folder = parent_folder
+      @session = @parent_folder.research_object.session
+    end
+
+    # The resource that this entry points to. Lazily loaded.
+    def resource
+      @resource ||= @parent_folder.research_object.resources(@resource_uri) ||
+                    @parent_folder.research_object.folders(@resource_uri) ||
+                    ROSRS::Resource.new(@parent_folder.research_object, @resource_uri)
+    end
+
+    ##
+    # Removes this folder entry from the folder. Does not delete the resource.
+    def delete
+      code = @session.delete_resource(@uri)[0]
+      @loaded = false
+      code == 204
+    end
+
+    def self.create(parent_folder, name, resource_uri)
+      code, reason, uri = parent_folder.research_object.session.add_folder_entry(parent_folder.uri, resource_uri, name)
+      self.new(parent_folder, name, uri, resource_uri)
+    end
+
+  end
+
+end

data/lib/wf4ever/rosrs/helper.rb

@@ -0,0 +1,12 @@
+module ROSRS
+  module Helper
+    def self.is_uri?(object)
+      if object.is_a?(URI) ||
+         object.is_a?(String) && (object.start_with?("/") || object.start_with?("http"))
+        true
+      else
+        false
+      end
+    end
+  end
+end

data/lib/wf4ever/rosrs/namespaces.rb

@@ -0,0 +1,42 @@
+#:nodoc: all
+
+module RDF
+
+  class AO < Vocabulary("http://purl.org/ao/")
+    # Declaring these might not be necessary
+    property :Annotation
+    property :body
+    property :annotatesResource
+  end
+
+  class ORE < Vocabulary("http://www.openarchives.org/ore/terms/")
+    property :Aggregation
+    property :AggregatedResource
+    property :Proxy
+    property :aggregates
+    property :proxyFor
+    property :proxyIn
+    property :isDescribedBy
+  end
+
+  class RO < Vocabulary("http://purl.org/wf4ever/ro#")
+    property :ResearchObject
+    property :AggregatedAnnotation
+    property :annotatesAggregatedResource
+    property :FolderEntry
+    property :Folder
+    property :Resource
+    property :entryName
+  end
+
+  class ROEVO < Vocabulary("http://purl.org/wf4ever/roevo#")
+    property :LiveRO
+  end
+
+  class ROTERMS < Vocabulary("http://ro.example.org/ro/terms/")
+    property :note
+    property :resource
+    property :defaultBase
+  end
+
+end

data/lib/wf4ever/rosrs/rdf_graph.rb

@@ -0,0 +1,72 @@
+# Shim class for RDF graph parsing, serialization, access
+module ROSRS
+  class RDFGraph
+
+    def initialize(options={})
+      # options: :uri =>    (URI to load),
+      #          :data =>   (string to load)
+      #          :format => (format of data)
+      @format = :rdfxml
+      @graph  = RDF::Graph.new
+      if options[:uri]
+        load_resource(options[:uri], options[:format])
+      end
+      if options[:data]
+        load_data(options[:data], options[:format])
+      end
+    end
+
+    def load_data(data, format=nil)
+      @graph << RDF::Reader.for(map_format(format)).new(data)
+    end
+
+    def load_resource(uri, format=nil)
+      raise NotImplementedError.new("Attempt to initialize RDFGraph from web resource: #{uri}")
+    end
+
+    def serialize(format=nil)
+      return RDF::Writer.for(map_format(format)).buffer { |w| w << @graph }
+    end
+
+    # other methods here
+
+    def has_statement?(stmt)
+      return @graph.has_statement?(stmt)
+    end
+
+    def each_statement(&block)
+      @graph.each_statement(&block)
+    end
+
+    def query(pattern, &block)
+      @graph.query(pattern, &block)
+    end
+
+    def match?(pattern)
+      pattern_found = false
+      @graph.query(pattern) { |s| pattern_found = true }
+      return pattern_found
+    end
+
+    # Private helpers
+
+    private
+
+    def map_format(format=nil)
+      rdf_format = :rdfxml  # default
+      if format
+        if format == :xml
+          rdf_format = :rdfxml
+        elsif format == :ntriples
+          rdf_format = :ntriples
+        elsif format == :turtle
+          rdf_format = :turtle
+        else
+          raise ArgumentError.new("Unrecognized RDF format: #{format}")
+        end
+      end
+      return rdf_format
+    end
+
+  end
+end