rohbau 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8d05d28272851e7d359b3640cdb9e4a21250f704
-  data.tar.gz: 183ca9c967b841d7dc8e4bc6dbdd57e222eab5fc
+  metadata.gz: aba07a5627f76c6095247bcbfbd5ef8f4cc3e221
+  data.tar.gz: 79c36065afca542bc02b79a77eca590e4b9bdde4
 SHA512:
-  metadata.gz: 9b144522c39a33baa618b912f17e3f9a2a6f743a910194cc052409cd890992a0994eb629da418eb5b5d8cb1816f64159f944c9daada4b55546b1b58f71a86529
-  data.tar.gz: 9e6e8cd4e34c668c81172180d3ca99b64af7d5b32e9b1d19a35a72c420e2ad15eda820b0c122f6529bb2a946fe56c0a1d7dbc854bb5b4e458791edfd661e96f7
+  metadata.gz: f3951dabbee7a5af8d4e279935b33bed6475ec31a4b90ed8446ad03b6b89c93496ddcc26f6c1feaf849aee1316bf8ef0b9b6eda065a071e40bf6e34347459ed7
+  data.tar.gz: 54b582e38ce22964cdc44b87f0b3a2f2aa776bd6241b0bd74f5dcbe7180970635c8cbff8b72ed15256ff9197f9d4f12391790567e6a4ffeca0171c95d14b456c

data/.rubocop.yml

@@ -0,0 +1,18 @@
+# Generated by `rubocop --auto-gen-config`
+inherit_from: .rubocop_todo.yml
+
+Metrics/LineLength:
+  Exclude:
+    - rohbau.gemspec
+    - examples/**/*.rb
+
+Style/AlignParameters:
+  EnforcedStyle: with_fixed_indentation
+
+# Prefer foo: :bar
+Style/HashSyntax:
+  EnforcedStyle: hash_rockets
+
+# Let Inch check that
+Style/Documentation:
+  Enabled: false

data/.rubocop_todo.yml

@@ -0,0 +1,149 @@
+# This configuration was generated by `rubocop --auto-gen-config`
+# on 2015-03-08 22:50:04 +0100 using RuboCop version 0.29.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 1
+Lint/HandleExceptions:
+  Enabled: false
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Lint/UnusedBlockArgument:
+  Enabled: false
+
+# Offense count: 2
+# Cop supports --auto-correct.
+Lint/UnusedMethodArgument:
+  Enabled: false
+
+# Offense count: 2
+Lint/UselessComparison:
+  Enabled: false
+
+# Offense count: 2
+Lint/Void:
+  Enabled: false
+
+# Offense count: 1
+Metrics/AbcSize:
+  Max: 20
+
+# Offense count: 3
+# Configuration parameters: CountComments.
+Metrics/MethodLength:
+  Max: 14
+
+# Offense count: 2
+Style/AccessorMethodName:
+  Enabled: false
+
+# Offense count: 2
+Style/CaseEquality:
+  Enabled: false
+
+# Offense count: 2
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+# Offense count: 2
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/ClassCheck:
+  Enabled: false
+
+# Offense count: 3
+Style/DoubleNegation:
+  Enabled: false
+
+# Offense count: 1
+Style/EachWithObject:
+  Enabled: false
+
+# Offense count: 8
+# Configuration parameters: MinBodyLength.
+Style/GuardClause:
+  Enabled: false
+
+# Offense count: 6
+# Configuration parameters: MaxLineLength.
+Style/IfUnlessModifier:
+  Enabled: false
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: IncludeSemanticChanges.
+Style/NonNilCheck:
+  Enabled: false
+
+# Offense count: 2
+# Cop supports --auto-correct.
+# Configuration parameters: PreferredDelimiters.
+Style/PercentLiteralDelimiters:
+  Enabled: false
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Style/PerlBackrefs:
+  Enabled: false
+
+# Offense count: 1
+# Configuration parameters: NamePrefix, NamePrefixBlacklist.
+Style/PredicateName:
+  Enabled: false
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Style/Proc:
+  Enabled: false
+
+# Offense count: 3
+# Cop supports --auto-correct.
+Style/RedundantSelf:
+  Enabled: false
+
+# Offense count: 3
+# Configuration parameters: MaxSlashes.
+Style/RegexpLiteral:
+  Enabled: false
+
+# Offense count: 12
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/SignalException:
+  Enabled: false
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Style/SpecialGlobalVars:
+  Enabled: false
+
+# Offense count: 31
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/StringLiterals:
+  Enabled: false
+
+# Offense count: 1
+Style/StructInheritance:
+  Enabled: false
+
+# Offense count: 7
+# Cop supports --auto-correct.
+# Configuration parameters: ExactNameMatch, AllowPredicates, AllowDSLWriters, Whitelist.
+Style/TrivialAccessors:
+  Enabled: false
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Style/UnneededPercentQ:
+  Enabled: false
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: WordRegex.
+Style/WordArray:
+  MinSize: 2

data/.travis.yml

@@ -1,6 +1,7 @@
 language: ruby
 sudo: false
 cache: bundler
+script: "bundle exec rake ci"
 rvm:
   - ruby-head
   - 2.2
@@ -12,6 +13,7 @@ rvm:
   - jruby-19mode # JRuby in 1.9 mode
 env:
   global:
+    - CODECLIMATE_REPO_TOKEN=bff5110004e542a78ce5dd5fb7f154ac06cdc5a564d54957656a56e79bf1a031
     - JRUBY_OPTS='--dev -J-Xmx1024M'
 matrix:
   fast_finish: true

data/Gemfile

@@ -6,3 +6,7 @@ gemspec
 if ENV['CODECLIMATE_REPO_TOKEN']
   gem "codeclimate-test-reporter", :group => :test, :require => nil
 end
+
+group :tools do
+  gem 'rubocop'
+end

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2013 TODO: Write your name
+Copyright (c) 2013-2015 Neopoly GmbH
 
 MIT License
 

data/README.md

@@ -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,6 +52,8 @@ 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
 require 'rohbau/runtime'
 require 'rohbau/runtime_loader'
@@ -67,6 +69,14 @@ module MyApplication
   end
 end
 
+```
+
+`examples/user_service/runtime.rb`
+
+```ruby
+require 'rohbau/runtime'
+require 'rohbau/runtime_loader'
+
 module UserService
   class RuntimeLoader < Rohbau::RuntimeLoader
     def initialize
@@ -78,10 +88,23 @@ module UserService
   end
 end
 
+```
+
+`examples/runtime.rb`
+
+```ruby
+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
@@ -105,17 +128,6 @@ MyApplication::RuntimeLoader.running? # => false
 
 ```
 
-##### Registrar
-
-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`.
-
-##### List of plugins
-
-Accordingly to the sample above `MyApplication::RuntimeLoader` knows about it's registered plugins.
-`MyApplication::RuntimeLoader.plugins` therefore returns `{:user_service => UserService::RuntimeLoader}`.
-
 ### ServiceFactory
 
 The `ServiceFactory` is considered the authority for retrieval of service instances.
@@ -125,6 +137,8 @@ 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
 require 'rohbau/service_factory'
 
@@ -152,33 +166,403 @@ registry.user_service # => NoMethodError: undefined method `user_service'
 
 Validate registered dependencies
 
+`examples/user_service/service_factory_validation.rb`
+
 ```ruby
+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 # => []
+
+```
+
+### Request
+
+It ensures an initialized runtime and builds up a new the service factory instance.
+
+`examples/user_service/request.rb`
+
+```ruby
+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
+
+```
+
+### Entity
+
+Entities are low level, logic-less, data structures.
+
+`examples/user_entity.rb`
+
+```ruby
+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
+
+```
+
+### Gateway
+
+Provides an interface to persist entities.
+
+`examples/user_service/user_gateway.rb`
+
+```ruby
+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
+
+```
+
+### UseCase
+
+`UseCases` define the interface for the end user who interacts with the system.
+
+#### Examples
+
+Define a class that inherits from `Rohbau::UseCase` which has a `#call` method:
+
+`examples/user_service/create_user_use_case.rb`
+
+```ruby
+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
+
+```
+
+And call the CreateUser use case as follows:
+
+`examples/use_case.rb`
+
+```ruby
+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'
+
+```
+
+Alternately, use cases can be called using `Interface`, which is detailed in the next section.
+
+### Interface
+
+`Interface` allows for simpler and more semantic use case calling, with the additional benefit of fine grain control of return values and spy-like access in a test context.  
+
+**Please note**: `Interface` requires an `Input` class in your use case, as well as a `Success` class if you are using the stub features.
+
+In a nutshell, `Interface` allows your use case calls to go from this:
+
+```ruby
+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
+input = {
+  :user_data => {
+    :nickname => 'Bob'
+  }
+}
+UserService::CreateUser.new(request, input).call
+
+```
+
+To this:
+
+```ruby
+require 'rohbau/interface'
+require 'user_service/create_user_use_case'
+
+interface = Rohbau::Interface.new
+interface.user_service :create_user, :user_data => {
+  :nickname => 'Bob'
+}
+```
+
+This increased simplicity is very helpful, but the majority of `Interface`'s usefulness becomes accessible while testing. Assume the following use case:
+
+```ruby
+module UserService
+  module UseCases
+    class CreateUser
+      Input = Bound.required :user_data
+      Success = Bound.required :user_uid
+      Error = Bound.required :message
+
+      def initialize(request, input)
+        @request = request
+        @user_data = input.user_data
+      end
+
+      def call
+        result = service(:user_service).create(@user_data)
+
+        if result.nil?
+          Error.new :message => "Something went wrong"
+        else
+          Success.new :user_uid => "uid_for_#{user_data.nickname}"
+        end
+      end
+    end
+  end
+end
+```
+#### Stubbing use case return values
+
+Let's assume this use case will be called, along with many other use cases, by the frontend framework of your choosing.  
+
+Frontend tests should be implemented with the actual objects they would use in production, but since test isolation is an important concept in DDD, the `UserService` domain, which is outside of the scope of the frontend, should never actually be called.
+
+Beyond this, we will also want to stub return values to create the various test cases we may have - when there is no user present, for example.  
+
+These requirements can be realized by passing the following keys to your use case:
+
+ * `:stub_result`
+ When the `stub_result` key is present, its value will be passed to the called use case and returned in subsequent calls to that same use case as a `Success` object.
+ * `:stub_type`
+ Much like the `stub_result` key, the `stub_type` key allows the type of return value to be overwritten, provided, of course, that it is a type which is defined by your use case.
+
+```ruby
+require 'rohbau/interface'
+
+describe 'stubbing use case return values' do
+  let(:interface) { Rohbau::Interface.new }
+
+  it 'returns subsequent calls to the same use case as stubs' do
+    interface.user_service :create_user, :stub_result => {
+      :user_data => { :user_uid => "definitely NOT bob's uid" }
+    }
+
+    result = interface.user_service :create_user, :user_data => {
+      :nickname => 'bob'
+    }
+
+    assert_kind_of UserService::UseCases::CreateUser::Success, result
+    assert_equal "definitely NOT bob's uid", result.user_uid
+  end
+
+  it 'can also return other result types' do
+    interface.user_service :create_user,
+      :stub_type => :Error,
+      :stub_result => {
+        :message => "error"
+      }
+
+    result = interface.user_service :create_user
+
+    assert_kind_of UserService::UseCases::CreateUser::Error, result
+    assert_equal 'error', result.message
+  end
+end
+```
+#### Test spying
+
+Sometimes it's helpful to look into the use case and see some details about how it has been called.  There are two methods to this end, each of which returns a hash with keys corresponding to each use case which has been called:
+
+ * `interface.calls` is further keyed by argument and returns the value passed to the given argument.
+ * `interface.call_count` returns the number of times a given use case has been called.
+
+```ruby
+require 'rohbau/interface'
+
+describe 'spying on tests' do
+  let(:interface) { Rohbau::Interface.new }
+
+  it 'records passed arguments by use_case' do
+    interface.user_service :create_user, :user_data => {
+      :nickname => 'bob'
+    }
+
+    result = interface.calls[:create_user][:user_uid]
+
+    assert_equal "23", result
+  end
+
+  it 'records number of unstubbed calls to each use_case' do
+    interface.user_service :create_user, :stub_result => {
+      :user_data => { :user_uid => 'something else' }
+    }
+
+    interface.user_service :create_user, :user_data => {
+      :nickname => 'bob'
+    }
+
+    interface.user_service :create_user, :user_data => {
+      :nickname => 'bob'
+    }
+
+    assert_equal 2, interface.call_count[:create_user]
+  end
+end
+```
+
+#### Cleaning up
+
+`Interface` provides the following two convenience methods for cleaning up your test environment:
+
+ * `interface.clear_stubs` does what it says on the tin - All recorded arguments, call counts, stubbed results and stubbed types are cleared.
+ * `interface.clear_cached_requests` empties the request cache.
+
+```ruby
+require 'rohbau/interface'
+
+let(:interface) { Rohbau::Interface.new }
+it 'can clear all stubbed results' do
+  interface.user_service :create_user, :stub_result => {
+    :user_data => { :user_uid => 'something else' }
+  }
+
+  result = interface.user_service :create_user, :user_data => {
+    :nickname => 'bob'
+  }
+
+  assert_equal 'something else', result.user_uid
+
+  interface.clear_stubs
+
+  result = interface.user_service :create_user, :user_data => {
+    :nickname => 'bob'
+  }
+
+  refute_equal 'something else', result.user_uid
+  assert_equal 'uid_for_bob', result.user_uid
+end
+```
+
+### EventTube
+
+The `EventTube` implements the `Publish-subscribe` pattern. You can subscribe to events and publish them.
+
+#### Examples
+
+`examples/email_service/email_service.rb`
+
+```ruby
+class EmailService
+  def self.send_user_registration_email_to(user)
+    print "Send out email to #{user.nickname}"
+  end
+end
+
+```
+
+`examples/user_service/event_tube.rb`
+
+```ruby
+require 'rohbau/event_tube'
+
+module UserService
+  class EventTube < Rohbau::EventTube
+  end
+end
+
 ```
 
 ## 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
+```
+
+To verify all examples run:
+
+```bash
+rake examples:verify
 ```
 
-Always commit README.md.template and README.md together.
+Note: Examples will be verified during CI run.
+
 
 ## Contributing