rddd 0.1.2 → 0.1.3

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rddd (0.1.1)
+    rddd (0.1.2)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -8,28 +8,103 @@ Intention of rddd is to provide basic skeleton for DDD ruby application. Its fra
 ## Key goals
 
 * Provide basic DDD elements
-* Support separation of domain from delivery mechanism (MVC framework)
+* Support separation of domain from delivery mechanism (mostly web framework such Rails or Sinatra)
 * Support separation of domain from persistancy mechanism
 
-## Basic elements
+## Basic architecture
 
-As defined in DDD itself, framework has couple basic object types:
+![Architecture overview](https://github.com/petrjanda/rddd/blob/master/documentation/rddd.png?raw=true)
 
-* Services - use cases
-* Entities - domain objects with identity
-* Aggregate roots - entities roots to setup consistency boundaries
-* Repositories - abstraction over persistancy providing collections of aggregate roots
-
-Alongside core DDD object types, there is couple supporting ones, mostly factories.
+There are two major entry points to the domain layer from the delivery mechanism. Service bus, for a command execution and 
+Presenter factory, to build up the presented business data (views / reports).
 
 ### Service bus
 
 To further enhance the separation of delivery mechanism and domain from each other, every call to the domain service is done through the ```Service bus```. The key design goal is to decouple concrete service implementation from the non-domain code, so they never have to be directly instantiated outside the domain itself. Instead, service bus defines simple protocol for any object, which can call its ```execute``` method with service name and parameters. The instantiation of the service object then becomes implementation detail of domain code, thus leaves the flexibility for alternative solutions within domain.
 
-## Project structure
+In Rails application, it might look like:
+
+    class ProjectsController < ApplicationController
+      include ServiceBus
+
+      def create
+        execute(:create_project, params) do |errors|
+          render :new, :errors => errors
+          return
+        end
+
+        redirect_to projects_path, :notice => 'Project was successfully created!'
+      end
+    end 
+
+### Presenter factory
+
+We dont wanna DM (Delivery mechanism) know too much about domain implementation internals. Neither about specific presenter classes. We apply same approach as for Service bus and define simple interface to load a specific view.
+
+In Rails application, it might be used as:
+
+    class ProjectsController < ApplicationController
+      def index
+        PresenterFactory.build(:projects_by_account, :account_id => params[:account_id])
+      end
+    end
+
+### Services
+
+Service is the object to represent a single use case. Its responsibility is to orchestrate the cooperation of multiple aggregate roots (and entities), in a given order defined by use case.
+
+Service takes a list of attributes, which are necessary to execute the given use case. At the end nothing is returned, so service represent the command to the domain and doesn't return any data back. Therefore, client code should construct and pass all the data for the given use case and keep them, so it doesn't have to use presenters to load the result of the operation back.
+
+### Presenters
+
+Presenter is the view to the domain data, which is typically aggregation over multiple aggregate roots and entities. In other
+language presenter is report. In Rddd, views output plain Ruby hashes, thus no domain object is leaking outside the domain
+itself. The key design goal was to dont let framework later call any additional adhoc methods. Thats why framework doesn't interact with view object directly and pure Hash is returned back.
+
+### Aggregate root, entity, repository
+
+TBA
+
+## Planned features
+
+* Asynchronous notifications from services - Services might be executed synchronous but also asynchronous way. Simple extension of Service bus would do the trick (add ```execute_async``` method). Its a common case that client code might
+be waiting for the result from background job execution so it can talk back to user. There is a plan to add ```Notifier``` interface, which would be available during service execution. This interface should get concrete implementation within delivery mechanism (websockets, ...).
+
+## Project file structure
 
 Recommented project file structure:
 
     app/entities
     app/repositories
-    app/services
+    app/services
+
+## Author(s)
+
+* Petr Janda ([petr@ngneers.com](mailto:petr@ngneers.com))
+
+Wanna participate? Drop me a line.
+
+## License
+
+Copyright (c) 2012 Petr Janda
+
+MIT License
+
+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/lib/rddd/entity.rb

@@ -5,7 +5,7 @@ class Rddd::Entity
     @id = id
   end
 
-  def ==(b)
-    @id == b.id
+  def ==(other)
+    @id == other.id
   end
 end

data/lib/rddd/service_bus.rb

@@ -40,7 +40,7 @@ module Rddd
     # @param {Hash} Attributes to be passed to the service call.
     # @param {Block} Optional error callback block.
     #
-    def execute(service_name, attributes = {})    
+    def execute_service(service_name, attributes = {})
       raise InvalidService unless service = build_service(service_name, attributes)
 
       unless service.valid?

data/lib/rddd/service_factory.rb

@@ -11,7 +11,7 @@ module Rddd
 
     def self.camel_case(string)
       return string if string !~ /_/ && string =~ /[A-Z]+.*/
-      string.split('_').map{|e| e.capitalize}.join
+      string.split('_').map{|token| token.capitalize}.join
     end
   end
 end

data/lib/rddd/version.rb

@@ -1,3 +1,3 @@
 module Rddd
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

data/spec/integration_spec.rb

@@ -27,7 +27,7 @@ class ProjectsController
   include Rddd::ServiceBus
 
   def create(params)
-    execute(:create_project, params)
+    execute_service(:create_project, params)
   end
 end
 

data/spec/lib/service_bus_spec.rb

@@ -8,8 +8,8 @@ describe Rddd::ServiceBus do
     stub('controller').tap { |controller| controller.extend Rddd::ServiceBus }
   end
 
-  describe '.execute' do
-    subject { controller.execute(:foo, attributes) }
+  describe '.execute_service' do
+    subject { controller.execute_service(:foo, attributes) }
 
     let(:service) { stub('service', :valid? => true, :execute => nil) }
 
@@ -57,7 +57,7 @@ describe Rddd::ServiceBus do
           Rddd::ServiceFactory.expects(:build).with(:foo, attributes).returns(service)
           service.expects(:execute).never
 
-          controller.execute(:foo, attributes, &error_block)
+          controller.execute_service(:foo, attributes, &error_block)
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rddd
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
   prerelease: 
 platform: ruby
 authors:
@@ -26,6 +26,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- documentation/rddd.png
 - lib/rddd.rb
 - lib/rddd/aggregate_root.rb
 - lib/rddd/aggregate_root_finders.rb