rohbau 0.1.0 → 0.2.0

data/README.md.template

@@ -24,7 +24,7 @@
 
 ## Description
 
-Rohbau provides a set of patterns used in Domain Driven Design.
+_Rohbau_ provides a set of patterns used in Domain Driven Design.
 
 ## Installation
 
@@ -52,20 +52,23 @@ By this a place is made where for example memories for in-memory gateway backend
 
 Inject a user service to your application
 
+`examples/my_application.rb`
+
 ```ruby
-include_example runtime
+include_example 'my_application'
 ```
 
-##### Registrar
+`examples/user_service/runtime.rb`
 
-Every injected `RuntimeLoader` knows about it's registrar.
-In the example above `UserService::RuntimeLoader` has been injected to `MyApplication::RuntimeLoader`.
-`UserService::RuntimeLoader.registrar` therefore returns `MyApplication::RuntimeLoader`.
+```ruby
+include_example 'user_service/runtime'
+```
 
-##### List of plugins
+`examples/runtime.rb`
 
-Accordingly to the sample above `MyApplication::RuntimeLoader` knows about it's registered plugins.
-`MyApplication::RuntimeLoader.plugins` therefore returns `{:user_service => UserService::RuntimeLoader}`.
+```ruby
+include_example 'runtime'
+```
 
 ### ServiceFactory
 
@@ -76,39 +79,120 @@ It follows partly the service locator / registry pattern.
 
 Register and unregister default service and override with specific service.
 
+`examples/user_service/service_factory.rb`
+
 ```ruby
-include_example service_factory
+include_example 'service_factory'
 ```
 
 Validate registered dependencies
 
+`examples/user_service/service_factory_validation.rb`
+
+```ruby
+include_example 'service_factory_validation'
+```
+
+### Request
+
+It ensures an initialized runtime and builds up a new the service factory instance.
+
+`examples/user_service/request.rb`
+
+```ruby
+include_example 'user_service/request'
+```
+
+### Entity
+
+Entities are low level, logic-less, data structures. 
+
+`examples/user_entity.rb`
+
 ```ruby
-MyServiceFactory.external_dependencies :user_service
-MyServiceFactory.missing_dependencies # => [:user_service] 
-MyServiceFactory.external_dependencies_complied? # => false
+include_example 'user_entity'
+```
+
+### Gateway
+
+Provides an interface to persist entities.
+
+`examples/user_service/user_gateway.rb`
 
-MyServiceFactory.register(:user_service) { Object.new } # => :user_service 
-MyServiceFactory.external_dependencies_complied? # => true 
-MyServiceFactory.missing_dependencies # => [] 
+```ruby
+include_example 'user_service/user_gateway'
+```
+
+### UseCase
+
+`UseCases` define the interface for the end user who interacts with the system.
+
+#### Examples
+
+`examples/user_service/create_user_use_case.rb`
+
+```ruby
+include_example 'user_service/create_user_use_case'
+```
+
+`examples/use_case.rb`
+
+```ruby
+include_example 'use_case'
+```
+
+### EventTube
+
+The `EventTube` implements the `Publish-subscribe` pattern. You can subscribe to events and publish them.
+
+#### Examples
+
+`examples/email_service/email_service.rb`
+
+```ruby
+include_example 'email_service/email_service'
+```
+
+`examples/user_service/event_tube.rb`
+
+```ruby
+include_example 'user_service/event_tube'
 ```
 
 ## Build README
 
-Make changes to README.md.template, not to README.md
+Make changes to `README.md.template`, not to `README.md`
 
 Include examples with
 
 ```bash
-include_example example_file_name
+include_example 'example_file_name'
 ```
 
 Build README.md with
 
 ```bash
-  ./bin/build_readme
+rake build_readme
+```
+
+Always commit `README.md.template` and `README.md` together.
+
+## Examples
+
+Run all examples via
+
+```bash
+rake examples
 ```
 
-Always commit README.md.template and README.md together.
+To verify all examples run:
+
+```bash
+rake examples:verify
+```
+
+Note: Examples will be verified during CI run.
+
 
 ## Contributing
 

data/Rakefile

@@ -1,5 +1,5 @@
 require 'bundler/gem_tasks'
-require "rake/testtask"
+require 'rake/testtask'
 
 Rake::TestTask.new(:spec) do |t|
   t.libs += ['spec', 'lib']

data/bin/build_readme

@@ -1 +1,3 @@
-cat README.md.template | etc/build_readme.rb > README.md
+#!/bin/bash
+
+echo 'Please use `rake build_readme`'

data/examples/email_service/email_service.rb

@@ -0,0 +1,5 @@
+class EmailService
+  def self.send_user_registration_email_to(user)
+    print "Send out email to #{user.nickname}"
+  end
+end

data/examples/event_tube.rb

@@ -0,0 +1,9 @@
+require 'user_service/event_tube'
+require 'user_service/user_gateway'
+require 'email_service/email_service'
+
+UserService::EventTube.subscribe :user_registered do |event|
+  EmailService.send_user_registration_email_to event.user # => 'Send out email to Bob'
+end
+
+UserService::UserGateway.new.create(:nickname => 'Bob')

data/examples/my_application.rb

@@ -0,0 +1,13 @@
+require 'rohbau/runtime'
+require 'rohbau/runtime_loader'
+
+module MyApplication
+  class RuntimeLoader < Rohbau::RuntimeLoader
+    def initialize
+      super(Runtime)
+    end
+  end
+
+  class Runtime < Rohbau::Runtime
+  end
+end

data/examples/runtime.rb

@@ -1,32 +1,15 @@
-require 'rohbau/runtime'
-require 'rohbau/runtime_loader'
-
-module MyApplication
-  class RuntimeLoader < Rohbau::RuntimeLoader
-    def initialize
-      super(Runtime)
-    end
-  end
-
-  class Runtime < Rohbau::Runtime
-  end
-end
-
-module UserService
-  class RuntimeLoader < Rohbau::RuntimeLoader
-    def initialize
-      super(Runtime)
-    end
-  end
-
-  class Runtime < Rohbau::Runtime
-  end
-end
+require 'my_application'
+require 'user_service/runtime'
 
 # Register user service on my application runtime
 MyApplication::Runtime.register :user_service, UserService::RuntimeLoader
+
+# My application runtime knowns about the registered plugins
 MyApplication::Runtime.plugins # => {:user_service=>UserService::RuntimeLoader}
 
+# The registered plugin knows his registrar
+UserService::RuntimeLoader.registrar # => MyApplication::Runtime
+
 # Runtimes are not initialized yet
 MyApplication::RuntimeLoader.instance # => nil
 MyApplication::Runtime.plugins[:user_service].instance # => nil

data/examples/service_factory_validation.rb

@@ -3,9 +3,9 @@ require 'rohbau/service_factory'
 MyServiceFactory = Class.new(Rohbau::ServiceFactory)
 
 MyServiceFactory.external_dependencies :user_service
-MyServiceFactory.missing_dependencies # => [:user_service] 
+MyServiceFactory.missing_dependencies # => [:user_service]
 MyServiceFactory.external_dependencies_complied? # => false
 
-MyServiceFactory.register(:user_service) { Object.new } # => :user_service 
-MyServiceFactory.external_dependencies_complied? # => true 
-MyServiceFactory.missing_dependencies # => [] 
+MyServiceFactory.register(:user_service) { Object.new } # => :user_service
+MyServiceFactory.external_dependencies_complied? # => true
+MyServiceFactory.missing_dependencies # => []

data/examples/use_case.rb

@@ -0,0 +1,10 @@
+require 'user_service/runtime'
+require 'user_service/request'
+require 'user_service/create_user_use_case'
+
+# Boot up user service
+UserService::RuntimeLoader.new
+
+request = UserService::Request.new
+
+UserService::CreateUser.new(request, :nickname => 'Bob').call # => 'Created user Bob'

data/examples/user_entity.rb

@@ -0,0 +1,20 @@
+require 'rohbau/entity'
+
+class User < Rohbau::Entity
+  attributes :uid, :nickname
+
+  def initialize(user_data = {})
+    self.nickname = user_data[:nickname]
+    super()
+  end
+end
+
+bob = User.new
+bob.nickname = 'Bob'
+bob.nickname # => 'Bob'
+
+other_bob = User.new
+other_bob.nickname = 'Bob'
+other_bob.nickname # => 'Bob'
+
+bob == other_bob # => true

data/examples/user_service/create_user_use_case.rb

@@ -0,0 +1,14 @@
+require 'rohbau/use_case'
+
+module UserService
+  class CreateUser < Rohbau::UseCase
+    def initialize(request, user_data)
+      super(request)
+      @user_data = user_data
+    end
+
+    def call
+      service(:user_service).create(@user_data)
+    end
+  end
+end

data/examples/user_service/event_tube.rb

@@ -0,0 +1,6 @@
+require 'rohbau/event_tube'
+
+module UserService
+  class EventTube < Rohbau::EventTube
+  end
+end

data/examples/user_service/request.rb

@@ -0,0 +1,16 @@
+require 'rohbau/request'
+require 'user_service/service_factory'
+
+module UserService
+  class Request < Rohbau::Request
+    def initialize(runtime = RuntimeLoader.instance)
+      super(runtime)
+    end
+
+    protected
+
+    def build_service_factory
+      ServiceFactory.new(@runtime)
+    end
+  end
+end

data/examples/user_service/runtime.rb

@@ -0,0 +1,13 @@
+require 'rohbau/runtime'
+require 'rohbau/runtime_loader'
+
+module UserService
+  class RuntimeLoader < Rohbau::RuntimeLoader
+    def initialize
+      super(Runtime)
+    end
+  end
+
+  class Runtime < Rohbau::Runtime
+  end
+end

data/examples/user_service/service_factory.rb

@@ -0,0 +1,10 @@
+require 'rohbau/service_factory'
+require 'user_service/user_gateway'
+
+module UserService
+  class ServiceFactory < Rohbau::ServiceFactory
+    register :user_service do
+      UserGateway.new
+    end
+  end
+end

data/examples/user_service/user_gateway.rb

@@ -0,0 +1,16 @@
+require 'user_service/event_tube'
+require 'user_entity'
+require 'rohbau/default_memory_gateway'
+
+module UserService
+  class UserGateway < Rohbau::DefaultMemoryGateway
+    def create(user_data)
+      user = User.new(user_data)
+      add(user)
+      EventTube.publish :user_registered, UserRegisteredEvent.new(user)
+    end
+
+    class UserRegisteredEvent < Struct.new(:user)
+    end
+  end
+end

data/examples/user_service.rb

@@ -0,0 +1 @@
+

data/examples/verify/examples.txt

@@ -0,0 +1,31 @@
+examples/email_service/email_service.rb
+
+examples/event_tube.rb
+Send out email to Bob
+examples/my_application.rb
+
+examples/runtime.rb
+
+examples/service_factory.rb
+examples/service_factory.rb:21:in `<main>': undefined method `user_service' for #<MyServiceFactory:0xa12e7b0> (NoMethodError)
+
+examples/service_factory_validation.rb
+
+examples/use_case.rb
+
+examples/user_entity.rb
+
+examples/user_service.rb
+
+examples/user_service/create_user_use_case.rb
+
+examples/user_service/event_tube.rb
+
+examples/user_service/request.rb
+
+examples/user_service/runtime.rb
+
+examples/user_service/service_factory.rb
+
+examples/user_service/user_gateway.rb
+

data/examples/verify/examples_spec.rb

@@ -0,0 +1,25 @@
+require 'minitest/autorun'
+
+describe 'Verify examples' do
+  let(:fixture_dir) do
+    Pathname.new(File.dirname(__FILE__))
+  end
+  let(:expected_output) do
+    File.read(fixture_dir.join('examples.txt'))
+  end
+
+  it 'verifies examples' do
+    actual, error = capture_subprocess_io do
+      system 'rake examples'
+    end
+
+    assert_possibly_equal actual, expected_output
+    assert_equal '', error
+  end
+
+  private
+
+  def assert_possibly_equal(exp, act)
+    assert_equal mu_pp_for_diff(exp), mu_pp_for_diff(act)
+  end
+end

data/lib/rohbau/application.rb

@@ -1,6 +1,5 @@
 module Rohbau
   module Application
-
     class RuntimeWrapper
       def self.wrap(&constructor)
         wrapper = Class.new do
@@ -37,12 +36,12 @@ module Rohbau
     end
 
     def domain_requests
-      domains.map{|d| d.const_get :Request }
+      domains.map { |d| d.const_get :Request }
     end
 
     def use_case_domains
       domains.select do |domain|
-        domain.const_defined?('UseCases')
+        domain.const_defined?(:UseCases)
       end
     end
 
@@ -54,17 +53,15 @@ module Rohbau
       end
 
       domains.inject([]) do |use_cases, domain|
-
-        if domain.const_defined?('UseCases')
-          use_case_namespace = domain.const_get('UseCases')
+        if domain.const_defined?(:UseCases)
+          use_case_namespace = domain.const_get(:UseCases)
           use_case_namespace.constants.each do |use_case_class_name|
-            use_cases << use_case_namespace::const_get(use_case_class_name)
+            use_cases << use_case_namespace.const_get(use_case_class_name)
           end
         end
 
         use_cases
       end
     end
-
   end
 end

data/lib/rohbau/default_memory_gateway.rb

@@ -2,7 +2,6 @@ require 'rohbau/index'
 
 module Rohbau
   class DefaultMemoryGateway
-
     def initialize(memory = Index.new, services = {})
       @memory = memory
       @services = services
@@ -73,6 +72,5 @@ module Rohbau
     def gateway_for_entity(entity_name)
       service(:"#{entity_name}_gateway")
     end
-
   end
 end

data/lib/rohbau/entity.rb

@@ -1,12 +1,10 @@
 module Rohbau
-
   class Entity
     class << self; attr_accessor :__attributes__ end
     def self.attributes(*attributes)
       @__attributes__ ||= []
       @__attributes__ += attributes
 
-
       predicate_attributes = attributes.select do |attr|
         attr =~ /\?$/
       end
@@ -33,9 +31,9 @@ module Rohbau
     end
 
     protected
+
     def __attributes__
       self.class.__attributes__ || []
     end
   end
-
 end

data/lib/rohbau/event_tube.rb

@@ -3,6 +3,7 @@ module Rohbau
     def self.reset
       @subscriptions = nil
     end
+
     def self.publish(name, event)
       subscription_handler.handle(name, event)
     end
@@ -17,7 +18,7 @@ module Rohbau
 
     class SubscriptionHandler
       def initialize
-        @subscriptions = Hash.new do |h,k|
+        @subscriptions = Hash.new do |h, k|
           h[k] = []
         end
       end

data/lib/rohbau/index.rb

@@ -18,7 +18,6 @@ module Rohbau
     end
 
     def add(entity)
-
       if option?(:uid_generation)
         validate :add, entity
 
@@ -154,8 +153,8 @@ module Rohbau
         ensure_uid_exists!(uid)
       end
 
-
       private
+
       def ensure_uid!(uid)
         if uid.nil?
           raise argument_error('uid is missing')
@@ -175,7 +174,7 @@ module Rohbau
       end
 
       def ensure_entity_has_uid!(entity)
-        if !entity.uid
+        unless entity.uid
           raise argument_error('entity has no uid', entity)
         end
       end
@@ -187,13 +186,13 @@ module Rohbau
       end
 
       def ensure_entity_exists!(entity)
-        if !@memory.has_uid?(entity.uid)
+        unless @memory.has_uid?(entity.uid)
           raise argument_error('entity is unknown', entity)
         end
       end
 
       def ensure_uid_exists!(uid)
-        if !@memory.has_uid?(uid)
+        unless @memory.has_uid?(uid)
           raise argument_error('uid is unknown', uid)
         end
       end