sakai-info 0.1.0

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+sakai-info Change History
+=========================
+
+0.0.0
+-----
+
+*Released 2012-02-??*
+
+* Initial release
+* Oracle-only support
+* Limited CLI functionality
+

data/LICENSE

@@ -0,0 +1,8 @@
+This work is dedicated to the public domain. No rights reserved.
+
+I, the copyright holder of this work, hereby release it into the public
+domain. This applies worldwide.
+
+I grant any entity the right to use this work for any purpose, without
+any conditions, unless such conditions are required by law.
+

data/README.md

@@ -0,0 +1,148 @@
+sakai-info
+==========
+
+*sakai-info* is a command line tool and a suite of Ruby libraries which enable
+the exploration of a Sakai database without the intermediation of a Java VM or
+any official Sakai code.
+
+Because the primary goal of this tool is to assist in information gathering
+and troubleshooting, no capability to change the database is included in the
+tool or the libraries.
+
+Meta
+----
+last updated: 2012-02-19  
+author: David Adams (daveadams@gmail.com)  
+github url: https://github.com/daveadams/sakai-info
+
+Testing
+-------
+
+Tests are defined in ./test using Test::Unit. The default `rake` action is to
+run all tests.
+
+Building
+--------
+
+Use `rake` to test and build the gem:
+
+    $ rake gem:build
+    
+The resulting gem will be saved to the working directory as
+`sakai-info-0.1.0.gem`.
+
+Cleanup built gems using:
+
+    $ rake clean
+
+Installing
+----------
+
+Install the *sakai-info* gem locally with:
+
+    $ rake gem:install
+
+Uninstall with:
+
+    $ rake gem:uninstall
+
+Supported Databases
+-------------------
+
+For this release, only Oracle databases are supported. MySQL support is planned
+as soon as possible. Support for SQLite or some other lightweight database may
+be implemented for unit testing purposes.
+
+System Requirements
+-------------------
+
+For Oracle support, the `ruby-oci8` gem is required.
+
+So far, testing has occurred using Ruby 1.9.1p376 and Ruby 1.9.2p290, with
+version 2.0.6 of the `ruby-oci8` gem, on Ubuntu 10.04, against Oracle 11g
+R2 versions 11.2.0.1 and 11.2.0.3, using the Oracle Instant Client version
+11.2.0.3.
+
+Configuration
+-------------
+
+To run, *sakai-info* needs to be able to connect to your Sakai database server.
+It is possible to specify multiple instances to choose from at runtime.
+
+In this release, *sakai-info* expects a to find the config in a file located at
+`$HOME/.sakai-info`. The file must be in YAML format and can contain one or
+more Sakai database connection definitions. To define a single database
+connection, specify the file like this:
+
+    dbtype: oracle
+    username: sakai
+    password: <password>
+    service: SAKAIPROD
+    host: oracle.db
+    port: 1521
+
+The `port` value is optional, with a default of 1521. If your Oracle setup uses
+a `tnsnames.ora` file, then both `host` and `port` can be excluded, and
+`service` will be used to find the corresponding `tnsnames.ora` entry.
+
+Multiple instances may be specified by using the following format:
+
+    default: production
+    instances:
+      production:
+        dbtype: oracle
+        username: sakai
+        password: <password>
+        service: SAKAIPROD
+        host: oracle.db
+        port: 1521
+     test:
+       dbtype: oracle
+       username: sakai
+       password: <password>
+       service: SAKAITEST
+
+The `default` key identifies which of the connections under `instances` you
+wish to be used in the absence of any explicit specification. Other instances
+will be referenced by the corresponding YAML key (eg, `production` and `test`
+in the example above).
+
+Command Line Usage
+------------------
+
+After installing the gem, the `sakai-info` program should be found in your
+PATH. For this release, very limited functionality is included. For usage
+details, run:
+
+    $ sakai-info help
+
+Library Usage
+-------------
+
+To use the library in your own Ruby programs, simply specify:
+
+    require 'sakai-info'
+
+Further specifying `include SakaiInfo` will pull all object classes into the
+primary namespace and could save some typing. Be careful that class names such
+as `User`, `Site`, and `Group` do not conflict with other elements of your
+program.
+
+Full RDoc documentation for each class is not available in this release, but is
+planned for a future release.
+
+Change History
+--------------
+
+See CHANGELOG.md
+
+Future Plans
+------------
+
+See ROADMAP.md
+
+License
+-------
+This work is dedicated to the public domain. No rights are reserved. See
+LICENSE for more information.
+

data/ROADMAP.md

@@ -0,0 +1,37 @@
+sakai-info Roadmap
+==================
+
+*Last updated 2012-02-18 by daveadams@gmail.com*
+
+The most important things to get to after the initial release are:
+
+* MySQL support
+* Command-line access to all object types, properties, and relationships
+  understood by the library.
+* Full RDoc documentation of the library classes, properties, and methods
+
+Other things on the wishlist for future releases:
+
+* More complete object relationship support for full drilldown capability
+  * Gradebook/assignment/quiz interaction
+  * Quiz attempts per-student and per-quiz
+  * Assignment submissions per-assignment and per-student
+* Support for more Sakai objects
+  * OSP
+  * Forum topics and posts
+  * Private messages
+  * Events
+  * Sessions
+* Generalized reporting capabilities
+  * Storage utilization per-site
+  * Session and event statistics
+  * Metrics on various elements, eg:
+    * Typical quiz duration
+    * Quiz/assignment completion rates
+    * Forum post rates, post length
+    * etc
+
+The ultimate dream:
+
+* A web interface for searching and exploring the database
+

data/bin/sakai-info

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+#
+# sakai-info
+#   Command line tool for exploring the Sakai database via the
+#   sakai-info library
+#
+# Created 2012-02-15 daveadams@gmail.com
+# Last updated 2012-02-19 daveadams@gmail.com
+#
+# https://github.com/daveadams/sakai-info
+#
+# This software is public domain.
+#
+
+require 'sakai-info'
+include SakaiInfo
+
+require 'sakai-info/cli'
+
+ObjectModes = %w(site user)
+
+if ARGV.length > 0
+  case ARGV[0]
+
+  when "help" then
+    if ARGV.length > 1
+      CLI::Help.help ARGV[1]
+    else
+      CLI::Help.help
+    end
+    exit
+
+  when "version" then
+    puts VERSION
+    exit
+
+  when "validate" then
+    if CLI.validate_config
+      puts "Configuration OK"
+      exit
+    else
+      exit 1
+    end
+
+  when "test" then
+    STDERR.puts "PENDING: test mode unimplemented"
+    exit 1
+
+  else
+    # test to see if it's an accepted object mode
+    if ObjectModes.include? ARGV[0]
+      mode = ARGV[0]
+      ARGV.shift
+      # continue on
+
+    else
+      STDERR.puts "ERROR: Command '#{ARGV[0]}' was not recognized."
+      STDERR.puts "Run 'sakai-info help' for a list of commands."
+      exit 1
+    end
+  end
+else
+  STDERR.puts "ERROR: No command was given."
+  STDERR.puts "Run 'sakai-info help' for a list of commands."
+  exit 1
+end
+
+exit 1 if not CLI.validate_config
+
+if mode == "user"
+  print "Total users: "; STDOUT.flush
+  puts User.count
+
+elsif mode == "site"
+  print "Total sites: "; STDOUT.flush
+  puts Site.count
+
+end
+

data/lib/sakai-info.rb

@@ -0,0 +1,62 @@
+# sakai-info.rb
+#   Base library file
+#
+# Created 2012-02-15 daveadams@gmail.com
+# Last updated 2012-02-19 daveadams@gmail.com
+#
+# https://github.com/daveadams/sakai-info
+#
+# This software is public domain.
+#
+
+require 'yaml'
+require 'json'
+require 'rexml/document'
+require 'base64'
+
+require 'sakai-info/version'
+
+module SakaiInfo
+  # base exception class for distinguishing SakaiInfo exceptions
+  # from Ruby exceptions
+  class SakaiException < Exception; end
+
+  # exception to be raised when an object of a certain type cannot be found
+  class ObjectNotFoundException < SakaiException
+    def initialize(classname, identifier)
+      @classname = classname
+      @identifier = identifier
+
+      super("Could not find a #{@classname} object for '#{@identifier}'")
+    end
+  end
+end
+
+# extensions to other objects
+class String
+  def is_uuid?
+    self =~ /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+  end
+end
+
+# baseline config and connectivity
+require 'sakai-info/instance'
+require 'sakai-info/db'
+require 'sakai-info/configuration'
+
+# base objects
+require 'sakai-info/sakai_object'
+require 'sakai-info/sakai_xml_entity'
+
+# sakai object classes
+require 'sakai-info/user'
+require 'sakai-info/site'
+require 'sakai-info/announcement'
+require 'sakai-info/assignment'
+require 'sakai-info/authz'
+require 'sakai-info/content'
+require 'sakai-info/gradebook'
+require 'sakai-info/group'
+require 'sakai-info/message'
+require 'sakai-info/samigo'
+

data/lib/sakai-info/announcement.rb

@@ -0,0 +1,170 @@
+# sakai-info/announcement.rb
+#   SakaiInfo::Announcement library
+#
+# Created 2012-02-16 daveadams@gmail.com
+# Last updated 2012-02-16 daveadams@gmail.com
+#
+# https://github.com/daveadams/sakai-info
+#
+# This software is public domain.
+#
+
+module SakaiInfo
+  class AnnouncementChannel < SakaiXMLEntity
+    attr_reader :next
+
+    @@cache = {}
+    @@site_cache = {}
+
+    def self.find(id)
+      if @@cache[id].nil?
+        next_id = nil
+        xml = ""
+        DB.connect.exec("select next_id, xml from announcement_channel " +
+                        "where channel_id = :id", id) do |row|
+          nextid = row[0].to_i
+          REXML::Document.new(row[1].read).write(xml, 2)
+        end
+        if nextid.nil?
+          raise ObjectNotFoundException.new(AnnouncementChannel, id)
+        end
+        new_announcement = AnnouncementChannel.new(id, nextid, xml)
+        @@cache[id] = new_announcement
+        @@site_cache[new_announcement.site_id] = new_announcement
+      end
+      @@cache[id]
+    end
+
+    def self.find_by_site_id(site_id)
+      @@site_cache[site_id] ||=
+        if site_id == "!site"
+          self.find("/announcement/channel/#{site_id}/motd")
+        else
+          self.find("/announcement/channel/#{site_id}/main")
+        end
+    end
+
+    # raw data constructor
+    def initialize(id, nextid, xml)
+      @id = id
+      @next = nextid
+      @xml = xml
+      parse_xml
+    end
+
+    # properties
+    def announcements
+      @announcements ||= Announcement.find_by_channel_id(@id)
+    end
+
+    def announcement_count
+      @announcement_count ||= self.announcements.length
+    end
+
+    def site_id
+      @site_id ||= @id.split("/")[3]
+    end
+
+    # serialization
+    def default_serialization
+      {
+        "id" => self.id,
+        "next" => self.next,
+        "site_id" => self.site_id,
+        "announcement_count" => self.announcement_count
+      }
+    end
+
+    def summary_serialization
+      {
+        "id" => self.id,
+        "site_id" => self.site_id,
+        "announcement_count" => self.announcement_count
+      }
+    end
+  end
+
+  class Announcement < SakaiXMLEntity
+    attr_reader :channel, :owner, :date
+    attr_reader :draft, :pubview
+
+    @@cache = {}
+    def self.find(id)
+      if @@cache[id].nil?
+        channel = draft = pubview = owner = date = nil
+        xml = ""
+        DB.connect.exec("select channel_id, draft, pubview, owner, " +
+                        "to_char(message_date,'YYYY-MM-DD HH24:MI:SS'), xml " +
+                        "from announcement_message " +
+                        "where message_id = :id", id) do |row|
+          channel = AnnouncementChannel.find(row[0])
+          draft = row[1]
+          pubview = row[2]
+          owner = User.find(row[3])
+          date = row[4]
+          REXML::Document.new(row[5].read).write(xml, 2)
+        end
+        if date.nil?
+          raise ObjectNotFoundException.new(Announcement, id)
+        end
+        @@cache[id] = Announcement.new(id, channel, draft, pubview, owner, date, xml)
+      end
+      @@cache[id]
+    end
+
+    # raw data constructor
+    def initialize(id, channel, draft, pubview, owner, date, xml)
+      @id = id
+      @channel = channel
+      @draft = draft
+      @pubview = pubview
+      @owner = owner
+      @date = date
+      @xml = xml
+      parse_xml
+    end
+
+    # helpers
+    def self.find_by_channel_id(channel_id)
+      announcements = []
+      channel = AnnouncementChannel.find(channel_id)
+
+      DB.connect.exec("select message_id, draft, pubview, owner, " +
+                      "to_char(message_date,'YYYY-MM-DD HH24:MI:SS'), xml " +
+                      "from announcement_message " +
+                      "where channel_id = :channel_id", channel_id) do |row|
+        xml = ""
+        id = row[0]
+        draft = row[1]
+        pubview = row[2]
+        owner = User.find(row[3])
+        date = row[4]
+        REXML::Document.new(row[5].read).write(xml, 2)
+
+        @@cache[id] = Announcement.new(id, channel, draft, pubview, owner, date, xml)
+        announcements << @@cache[id]
+      end
+      announcements
+    end
+
+    # serialization
+    def default_serialization
+      {
+        "id" => self.id,
+        "date" => self.date,
+        "owner" => self.owner.serialize(:summary),
+        "draft" => self.draft,
+        "pubview" => self.pubview,
+        "channel" => self.channel.serialize(:summary)
+      }
+    end
+
+    def summary_serialization
+      {
+        "id" => self.id,
+        "date" => self.date
+      }
+    end
+  end
+end
+