lims-core 3.2.3

data/lib/lims-core/resource.rb

@@ -0,0 +1,21 @@
+# vi: ts=2 sts=2 et sw=2 spell spelllang=en  
+require 'common'
+require 'lims-core/base'
+require 'lims-core/subclass_tracker'
+
+module Lims::Core
+  module Resource
+    extend SubclassTracker
+    # We need to rename the actual self.included method
+    class << self
+      alias_method :tracker_included, :included
+    end
+    def self.included(klass)
+      klass.class_eval do
+        include Base
+      end
+      tracker_included(klass)
+    end
+  end
+end
+

data/lib/lims-core/subclass_tracker.rb

@@ -0,0 +1,30 @@
+# vi: ts=2 sts=2 et sw=2 spell spelllang=en  
+# This module allows a class or module to track
+# all of its descendants, i.e. being able to iterate
+# all over all subclasses (submodules) of the tracking class.
+# To do so, just include the following in the tracking class/module
+# then call ::subclasses.
+#
+
+module Lims
+  module Core
+    module SubclassTracker
+      def self.extended(klass)
+        (class <<klass; self; end).send :attr_accessor, :subclasses
+        (class <<klass; self; end).send :define_method, :inherited do |subclass|
+          klass.subclasses << subclass
+          super(subclass)
+        end
+        (class <<klass; self; end).send :define_method, :included do |submodule|
+        klass.subclasses << submodule
+        (class <<submodule; self; end).send :define_method, :inherited do |subclass|
+            klass.subclasses << subclass
+            super(subclass)
+          end
+          super(submodule)
+        end
+        klass.subclasses = []
+      end
+    end
+  end
+end

data/lib/lims-core/version.rb

@@ -0,0 +1,5 @@
+module Lims
+  module Core
+    VERSION = "3.2.3"
+  end
+end

data/lims-core.gemspec

@@ -0,0 +1,40 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "lims-core/version"
+
+Gem::Specification.new do |s|
+  s.name        = "lims-core"
+  s.version     = Lims::Core::VERSION
+  s.authors     = ["Maxime Bourget"]
+  s.email       = ["mb14@sanger.ac.uk"]
+  s.homepage    = ""
+  s.summary     = %q{Core of new LIMS system}
+  s.description = %q{Provide the core classes and persistence needed to build an API used by the pipelines applications.}
+  s.description = %q{provides all the necessary to interact with the core database}
+
+  s.rubyforge_project = "lims-core"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  # s.add_development_dependency "rspec"
+  # s.add_runtime_dependency "rest-client"
+  s.add_dependency('facets', '2.9.3')
+  s.add_dependency('virtus', '0.2.0')
+  s.add_dependency('aequitas')
+  s.add_dependency('modularity', '0.6.1')
+  s.add_dependency('dm-validations')
+  s.add_dependency('sequel')
+  s.add_dependency('activesupport')
+  s.add_dependency('uuid')
+  s.add_dependency('state_machine')
+  s.add_dependency('bunny', '0.9.0.pre10')
+
+
+  #development
+  s.add_development_dependency('rspec', '~> 2')
+  s.add_development_dependency('rake')
+end

data/makefile

@@ -0,0 +1,52 @@
+# Yes we could have use rake, but rake is so slow and verbose ...
+# Look at this as a collection of shell commands.
+
+.PHONY: migrate_test test doc clean clean_tree profile
+
+# launch rspec
+test:
+	bundle exec rspec
+
+focus:
+	bundle exec rspec -tfocus
+
+profile:
+	bundle exec rspec -p
+
+# generate yard doc
+doc:
+	bundle exec yardoc
+
+# migrate test database
+migrate_test:
+	bundle exec sequel -m db/migrations -e test config/database.yml
+
+# Start server for core presentation
+show:
+	bundle exec showoff serve showoff/core-2012-06-11
+
+# console
+console:
+	bundle exec sequel -e test config/database.yml
+        
+
+# generate constants tree of a starting required file
+constants:
+
+%.tree:
+	bundle exec ruby utils/constant_tree.rb $*  | tee $@
+
+core.tree: \ .tree
+	mv $< $@
+
+clean_tree:
+	rm *.tree
+
+clean: clean_tree
+
+guard:
+	bundle exec guard
+
+guardt:
+	bundle exec guard start Guardfile.tmux
+

data/showoff/core-2012-06-11/core/01_slide.md

@@ -0,0 +1,237 @@
+!SLIDE smaller transition=scrollLeft
+# `lims::core` 
+### A set of dependent components
+
+* API : `Actions`
+* Persistence : `Session`
+* Domain: `Laboratoy`, `LabProcess`, `Organization`
+
+### API => Persistence => Domains.
+!SLIDE small transition=scrollUp subsection
+# Lims::core
+## Principles
+* Models exists without the notion of persistence
+* Everything created within a `Session` is saved (at the end)
+* Everything manipulating objects is done through *external* `Actions`.
+
+!SLIDE small transition=scrollUp subsection
+# Lims::core
+## Foundation #
+### The lims::core is based on 3 gems :
+
+* `Facets` ruby extensions.
+* `Datamapper2` 
+	* `Virtus` - model definition
+	* <span class="red">`Aequitas`</span>- validation library
+* `Sequel` '*The database toolkit for ruby*'.
+
+.notes they both provide a full active record like 
+
+!SLIDE code  transition=scrollLeft smaller subsection
+#  Foundation
+## Virtus, Aequitas
+
+	@@@ ruby
+	class Sample
+	  include Virtus
+	  include Aequitas
+	  attribute :name, String, :required => true
+	end
+
+	s = Sample.new
+	s.valid? #=> false
+
+	s = Sample.new(:name => "my sample")
+	s.name #=> "my sample"
+	s.attributes #=> { :name => "my sample" }
+
+!SLIDE code   transition=scrollUp smaller subsection
+# Foundation
+## Sequel #
+
+	@@@ ruby
+	samples = DB[:samples] #=> proxy
+
+	samples.first #=> { :id  =>  1, :name => 'my sample' }
+
+	with_aliquots = samples.join(:aliquots, :sample_id => :id)
+	#=> proxy
+
+	samples_with_aliquots.first 
+	#=> { :sample_id => 1, :name => 'my sample', :id => 3)
+
+!SLIDE smaller  transition=scrollRight subsection
+# Persistence-less model
+## Plate declaration
+
+	@@@ ruby
+	class Plate
+	  include Resource
+	      # declare row_number and column_number
+	      %w(row column).each do |w|
+		attribute :"#{w}_number",  Fixnum, :required => true,
+			:gte => 0, :writer => :private
+	      end
+		
+		class Well
+		include Resource
+		...
+		end
+
+	      is_array_of Well do |p,t|
+		(p.row_number*p.column_number).times.map { t.new }
+	      end
+	end
+### Plate is like an Array
+
+!SLIDE code smaller transition=scrollUp subsection	
+# Persistence-less model
+## Plate spec
+
+	@@@ ruby
+	describe Plate do
+	    subject { Plate.new(:row_number => 8,
+						:column_number => 12) }
+
+	    it "can be indexed with a symbol " do
+	      subject[:B3].should be_a(Plate::Well)
+	      aliquot = mock(:aliquot)
+
+	      subject[:B3] << aliquot
+	      subject[:B3].should include(aliquot)
+	    end
+	end
+
+### Well is like an array too.
+
+
+!SLIDE small transition=scrollLeft
+# Session
+
+* A session is in charge of restoring and saving objects to a `Store`.
+* Every modifications within a session **block** is saved.
+* Everything is saved only once.
+* <span class="red">It's the only way to save an object</span>
+* It provides an **IdentityMap**.
+
+!SLIDE small transition=scrollUp subsection
+# Session 
+## Benefits #
+
+* Persistence operations not mixed with domain model.
+* Everything is automatically wrapped in a transaction.
+* Saves can be bulk (not implemented)
+* Eager loading (not implemented) can be set at session, or application level
+* Session information (user, date, client) can be audited in a `session` table
+
+!SLIDE small transition=scrollUp subsection
+# Session #
+## Purpose ##
+### Sessions have been designed to make some stuff hard for the developer as:
+
+* Load and save object(s) in different sessions.
+* Save an object in the middle of an *action* (method, function, ...).
+* User can't create a Session without a store
+
+### If you find yourself struggling trying to do something above, you **probably **shouldn't be doing it.
+
+
+
+!SLIDE smaller subsection transition=scrollLeft
+# Session #
+## Example
+
+	@@@ ruby
+	source_id = ...
+	# Session can't be created on its own
+	store.with_session(params) do |s|
+		# load a plate
+		source_plate = s.plate[source_id]
+
+		# create a new plate and add it to the session
+		s << target_plate= L::Plate.new(plate.attributes)
+
+		# transfer from one well to the another well
+		# modifies BOTH plates
+		target_plate[:A1] << source_plate[:C3].take(0.5)
+			
+	end # saves source and target
+
+
+!SLIDE small subsection transition=scrollUp
+# Session
+## API
+
+* Session needs to be created from a store :  
+  `store.with_session { |s| .... }`
+* Tells a session to manage an object :  
+  ` session << object_to_manage`
+* Load a object :  
+  `session.plate[plate_id]`
+* Get the id of an object  :  
+ `session.id_for(plate)`
+
+!SLIDE small subsection transition=scrollUp
+# Session
+## Objects no managed are not saved
+
+### The following code saves only one plate.
+
+	@@@ ruby
+	store.with_session do |s|
+		plate1 = new_plate
+		s << plate2=new_plate
+	end 
+
+### `plate2`.
+
+!SLIDE small subsection transition=scrollUp
+# Session
+## Object loaded are automatically managed
+
+	@@@ ruby
+	store.with_session do |s|
+		plate = s.plate[plate_id]
+		# s << plate  - unnecessary
+	end
+
+!SLIDE small subsection transition=scrollUp
+# Session
+## Post save block
+### Objects are saved at the end of a `with_session` block, but ids of new objects are only available after the block, when the session doesn't exist anymore.
+
+	@@@ ruby
+	store.with_session do |s|
+		s << new_plate = Plate.new(params)
+		{:new_plate => s.id_for(new_plate)}.to_json
+	end
+
+
+### Doesn't work.
+
+!SLIDE small subsection transition=shuffle 
+# Session / Post save block
+## returning the session ...
+
+	@@@ ruby
+	session, new_plate = store.with_session do |s|
+		s << new_plate = Plate.new(params)
+		[ s, new_plate ]
+	end
+
+	{:new_plate => session.id_for(new_plate}.to_json
+
+### Would probably work, but splits the block in 2 different places. Probably one of those things session has been to designed to make hard. 
+
+
+!SLIDE smaller subsection transition=shuffle 
+# Session / Post save block
+## Using a lambda
+
+	@@@ ruby
+	store.with_session  do |s|
+		s << new_plate = Plate.new(params)
+		lambda { {:new_plate => .id_for(new_plate)}.to_json }
+	end.call
+
+### Better, all the code is inside one block and the `lambda` is saying 'I am a future statement'. Note the `call` at the end.

data/showoff/core-2012-06-11/core/02_slide.md

@@ -0,0 +1,110 @@
+!SLIDE small transition=scrollLeft
+# Actions #
+## A  *reversible* functor:
+
+* Has parameters.
+* Can be called.
+* Can be reverted (when possible).
+
+### corresponding to an API call.
+
+!SLIDE small transition=scrollUp subsection
+# Actions #
+* Persistence aware
+* Called as-is by the API server.
+* Can be pipeline specific.
+* Executed within a `Session` and
+* ... a context (user, application).
+
+
+!SLIDE small transition=scrollUp subsection
+# Actions
+## How to call an action
+
+1. Pass context parameters (store, user, application),
+2. pass a parameters initializer block,
+3. call it.
+
+!SLIDE smaller subsection transition=scrollLeft
+# Actions / call
+## Example     
+	@@@ ruby
+	target_id = ...
+	source_id = ...
+    action = PlateTransfer.new(:store => store,
+							 :user => user,
+							 :application => application
+						 )  do |action, session|
+	      # session needed
+		  action.target = session.plate[target_id]
+		  action.source = session.plate[source_id]
+
+		  action.transfer_map = { :C3 => :B1 }
+	end 
+
+	action.call
+
+### This also separates parameter decoding from implementation, allowing
+parameters validation.
+	
+
+
+!SLIDE small transition=scrollRight subsection
+# Actions
+## Design
+* Include `Action`.
+* Declare parameters (attributes).
+* Implement `_call_in_session` to modify/create the model.
+* Attributes and results are automatically managed.
+
+!SLIDE smaller transition=scrollUp subsection
+# Actions / Design
+## PlateTransfer Action
+	@@@ ruby
+    class PlateTransfer
+      include Action
+
+      attribute :source, Laboratory::Plate, :required => true
+      attribute :target, Laboratory::Plate, :required => true
+      attribute :transfer_map, Hash, :required => true
+
+      # Transfers the content of  from source to target
+      # according to a transef map.
+      def _call_in_session(session)
+	    transfer_map.each do |from ,to|
+	      target[to] << source[from].take
+	    end
+	  end
+    end
+
+ 
+!SLIDE small transition=scrollRight
+# Done
+
+* Laboratory classes needed for pulldown.
+* Persistence on Laboratory.
+* SQL store and basic Persistors.
+* Transfer, Create Plate, Tube, and Tag  action.
+
+!SLIDE small transition=scrollLeft
+# To do
+* Manage `dirty` attributes
+* Integration with API server
+* Add samples
+* Add studies, projects
+* Submissions, orders
+
+!SLIDE small transition=scrollUp subsection
+# To do
+## wish list
+
+* Audit session
+* Eager loading
+* Bulk saving
+* Manage automatically relationship throug attributes.
+
+!SLIDE transition=shuffle
+# The End
+Any Questions ?
+
+