RubyGems - needle - Versions diffs - 1.2.0 → 1.2.1 - Mend

needle 1.2.0 → 1.2.1

Files changed (46) hide show

data/doc/manual-html/chapter-1.html +138 -78
data/doc/manual-html/chapter-2.html +180 -99
data/doc/manual-html/chapter-3.html +111 -75
data/doc/manual-html/chapter-4.html +80 -48
data/doc/manual-html/chapter-5.html +106 -56
data/doc/manual-html/chapter-6.html +82 -34
data/doc/manual-html/chapter-7.html +74 -38
data/doc/manual-html/chapter-8.html +70 -41
data/doc/manual-html/chapter-9.html +88 -63
data/doc/manual-html/index.html +6 -6
data/doc/manual-html/needle.png +0 -0
data/doc/manual-html/{manual.css → stylesheets/manual.css} +83 -10
data/doc/manual-html/stylesheets/ruby.css +17 -0
data/doc/manual/chapter.erb +20 -0
data/doc/manual/img/Needle.ai +0 -0
data/doc/manual/img/needle.png +0 -0
data/doc/manual/manual.rb +80 -5
data/doc/manual/manual.yml +3 -3
data/doc/manual/page.erb +1 -1
data/doc/manual/parts/01_use_cases.txt +70 -70
data/doc/manual/parts/02_creating.txt +19 -19
data/doc/manual/parts/02_namespaces.txt +29 -29
data/doc/manual/parts/02_services.txt +40 -41
data/doc/manual/parts/03_conventional.txt +20 -20
data/doc/manual/parts/03_locator.txt +44 -44
data/doc/manual/parts/04_overview.txt +1 -1
data/doc/manual/parts/04_setup.txt +32 -32
data/doc/manual/parts/customizing_contexts.txt +14 -14
data/doc/manual/parts/customizing_interceptors.txt +25 -25
data/doc/manual/parts/customizing_namespaces.txt +12 -12
data/doc/manual/parts/interceptors_attaching.txt +29 -30
data/doc/manual/parts/interceptors_custom.txt +16 -16
data/doc/manual/parts/interceptors_ordering.txt +5 -5
data/doc/manual/parts/libraries_creating.txt +18 -18
data/doc/manual/parts/libraries_using.txt +19 -19
data/doc/manual/parts/logging_configuration.txt +13 -13
data/doc/manual/parts/logging_logfactory.txt +21 -22
data/doc/manual/parts/models_models.txt +8 -8
data/doc/manual/parts/models_overview.txt +1 -1
data/doc/manual/parts/models_pipelines.txt +22 -22
data/doc/manual/{manual.css → stylesheets/manual.css} +83 -10
data/doc/manual/stylesheets/ruby.css +17 -0
data/lib/needle/definition-context.rb +3 -2
data/lib/needle/lifecycle/proxy.rb +1 -1
data/lib/needle/version.rb +1 -1
metadata +94 -85

@@ -14,7 +14,7 @@ product: !^product
   name: Needle
   tagline: to the point -->
   version: !!eval require "../../lib/needle/version"; Needle::Version::STRING
-  #logo: needle.png
+  logo: needle.png
   urls:
     - Project Page: http://rubyforge.org/projects/needle
     - User Manual: http://needle.rubyforge.org
@@ -23,8 +23,8 @@ product: !^product
     - Needle Wiki: http://needle.rubyforge.org/wiki/wiki.pl
 recent_updates:
-  - Described parameterized services
-  - Added multiton service models to list of available models
+  - Added Needle graphic (thanks to Bruce Williams)
+  - Added syntax highlighting to code blocks
 chapters:

data/doc/manual/page.erb CHANGED

@@ -1,7 +1,7 @@
 <html>
   <head>
     <title><%= manual.product.name %> Manual<% if object %> :: <%= object.page_title %><% end %></title>
-    <link type="text/css" rel="stylesheet" href="manual.css" />
+    <link type="text/css" rel="stylesheet" href="stylesheets/manual.css" />
   </head>
   <body>

data/doc/manual/parts/01_use_cases.txt CHANGED

@@ -7,7 +7,7 @@ Try these on for size:
 * "Log Method Execution":#logexec
 * "Reference Another Service":#refsvc
 * "Unit Testing":#unittest
-* "Lifecycle Management":#lifecycle
+* "Lifestyle Management":#lifestyle
 (Thanks to Howard Lewis Ship for his "HiveMind":http://jakarta.apache.org/hivemind documentation, from which some of the above bullet points were adapted.)
@@ -18,36 +18,36 @@ Needle has an integrated logging framework, and the ability to log execution tra
 Consider the following code, demonstrating how this would be done without Needle:
-<pre>
-  def foo( arg1, arg2 )
-    @log.debug( "in foo with #{arg1} and #{arg2}" ) if @log.debug?
-    ...
-    result = the_result_of_the_method
-    @log.debug( "finishing foo with #{result}" ) if @log.debug
-    return result
-  rescue Exception => e
-    @log.debug( "foo raised exception #{e.message} (#{e.class})" ) if @log.debug?
-    raise
-  end
-</pre>
+{{{lang=ruby,number=true,caption=Logging method execution without Needle
+def foo( arg1, arg2 )
+  @log.debug( "in foo with #{arg1} and #{arg2}" ) if @log.debug?
+  ...
+  result = the_result_of_the_method
+  @log.debug( "finishing foo with #{result}" ) if @log.debug
+  return result
+rescue Exception => e
+  @log.debug( "foo raised exception #{e.message} (#{e.class})" ) if @log.debug?
+  raise
+end
+}}}
 Now, multiply that by the number of methods in your class... the logging messages quickly overpower the rest of the code, and detract from the flow of your program. This makes your program harder to debug, test, and maintain.
 Now, consider the same method using Needle's integrated logging framework...
-<pre>
-  def foo( arg1, arg2 )
-    ...
-    return the_result_of_the_method
-  end
-</pre>
+{{{lang=ruby,number=true,caption=Logging method execution with Needle
+def foo( arg1, arg2 )
+  ...
+  return the_result_of_the_method
+end
+}}}
 Then, when you define the service that you want to add the logging to:
-<pre>
-  registry.register( :service_name_here ) { |reg| ... }
-  registry.intercept( :service_name_here ).with! { logging_interceptor }
-</pre>
+{{{lang=ruby,number=true,caption=Adding the logging interceptor to a service
+registry.register( :service_name_here ) { |reg| ... }
+registry.intercept( :service_name_here ).with! { logging_interceptor }
+}}}
 That's right. There's no explicit logging code in there. Instead, you just tell Needle that the methods of the class should be logged, and away it goes. This has the added benefit of allowing your objects to be unit tested, without spewing log messages everywhere.
@@ -55,41 +55,41 @@ h3. Reference Another Service <a name="#refsvc"></a>
 Invariably in a large application services will reference other services. This is typically accomplished through something like this:
-<pre>
-  class Component
-    ...
-    def foo( parms )
-      @service ||= lookup_service
-      @service.do_something( parms )
-    end
-    def lookup_service
-      ...
-    end
+{{{lang=ruby,number=true,caption=Looking up services without Needle
+class Component
+  ...
+  def foo( parms )
+    @service ||= lookup_service
+    @service.do_something( parms )
+  end
+  def lookup_service
     ...
   end
-</pre>
+  ...
+end
+}}}
 Whether the lookup is done lazily, as shown above, or when the class is first instantiated is irrelevant. The point is that you either have to implement a bunch of code to look up a service based on some criteria, or you hard code the class of the service (which creates tight coupling and makes things like unit testing harder).
 With Needle, you just declare a setter for the service, and then tell Needle that the class depends on the other service:
-<pre>
-  class Component
-    attr_writer :service
-    ...
-    def foo( parms )
-      @service.do_something( parms )
-    end
-    ...
+{{{lang=ruby,number=true,caption=Wiring services with Needle
+class Component
+  attr_writer :service
+  ...
+  def foo( parms )
+    @service.do_something( parms )
   end
+  ...
+end
-  registry.register( :component ) do |reg|
-    c = Component.new
-    c.service = reg.some_other_service
-    c
-  end
-</pre>
+registry.register( :component ) do |reg|
+  c = Component.new
+  c.service = reg.some_other_service
+  c
+end
+}}}
 Then, when your service is instantiated, Needle will automatically look for and instantiate the dependencies for you. This makes for cleaner code, and looser coupling between services.
@@ -101,34 +101,34 @@ Needle, by its very nature, encourages loose coupling of components. Also, becau
 Consider this tightly coupled example:
-<pre>
-  def foo( args )
-    @some_dependency ||= MyNewDependency.new
-    @some_dependency.do_something(args)
-  end
-</pre>
+{{{lang=ruby,number=true,caption=Tight coupling
+def foo( args )
+  @some_dependency ||= MyNewDependency.new
+  @some_dependency.do_something(args)
+end
+}}}
 It is impossible to test the method @#foo@ without also testing the MyNewDependency class. However, if the @@some_dependency@ object is made a property that is set externally, you can replace it at test time with a blank:
-<pre>
-  attr_writer :some_dependency
+{{{lang=ruby,number=true,caption=Loose coupling
+attr_writer :some_dependency
-  def foo( args )
-    @some_dependency.do_something( args )
-  end
-</pre>
+def foo( args )
+  @some_dependency.do_something( args )
+end
+}}}
 The unit test would become something like this:
-<pre>
-  def test_foo
-    @obj.some_dependecy = MyMockDependency.new
-    @obj.foo( args )
-    assert @obj.is_in_some_state
-  end
-</pre>
+{{{lang=ruby,number=true,caption=Unit testing with a mock object
+def test_foo
+  @obj.some_dependecy = MyMockDependency.new
+  @obj.foo( args )
+  assert @obj.is_in_some_state
+end
+}}}
-h3. Lifecycle Management <a name="#lifecycle"></a>
+h3. Lifestyle Management <a name="#lifestyle"></a>
 Singleton objects are a fact of life in complex systems. The singleton design pattern is powerful and useful. However, using the Singleton mixin, or declaring methods at the class level, can make your code difficult to unit test since the state of such objects cannot be easily reset.
@@ -136,6 +136,6 @@ Needle has a solution. You can tell Needle to treat a service as either a _proto
 Your object is still just a plain ol' ordinary Ruby object, but Needle has effectively transformed it into a singleton. This means you can unit test it as if it were nothing special, but when it is used in your application it will act like a singleton.
-Lifecycle management also means that you can control _when_ a service is instantiated.  The _prototype_ and _singleton_ models will always be instantiated as soon as they are requested. Sometimes, though, you don't want that--you'd like the instantiation to be deferred as late as possible.
+Lifestyle management also means that you can control _when_ a service is instantiated.  The _prototype_ and _singleton_ models will always be instantiated as soon as they are requested. Sometimes, though, you don't want that--you'd like the instantiation to be deferred as late as possible.
 With Needle, you can indicate that a service should use deferred instantiation. This will cause the service to not actually be instantiated until a method is actually invoked on it.  Using this model, you can have services depend on themselves, or other forms of cyclical dependencies.

data/doc/manual/parts/02_creating.txt CHANGED

@@ -1,39 +1,39 @@
 Creating a registry is as simple as calling @Needle::Registry.new@. This will give you a new registry object, bootstrapped to contain a few general services.
-<pre>
-  require 'needle'
+{{{lang=ruby,number=true,caption=Creating a registry
+require 'needle'
-  registry = Needle::Registry.new
-</pre>
+registry = Needle::Registry.new
+}}}
 Once you have the reference to the registry, you can register services with it, create new namespaces in it, and so forth.
 Alternatively, you can pass a block to @#new@:
-<pre>
-  registry = Needle::Registry.new do |r|
-    ...
-  end
-</pre>
+{{{lang=ruby,number=true,caption=Creating a registry with a block
+registry = Needle::Registry.new do |r|
+  ...
+end
+}}}
 The parameter to the block will be a reference to the registry. This allows you to register services with the registry as soon as it is created.
 Another convenience method is @#define!@:
-<pre>
-  registry = Needle::Registry.define! do
-    ...
-  end
-</pre>
+{{{lang=ruby,number=true,caption=Creating a registry with #define!
+registry = Needle::Registry.define! do
+  ...
+end
+}}}
 This block accepts no parameters, and evaluates the block as if it were passed to @Registry#define!@ (see below).
 There can be problems with using @define!@, however, since it uses @instance_eval@ to evaluate the block within the context of another object. If you find yourself running into scoping issues, you might want to consider using @#define@:
-<pre>
-  registry = Needle::Registry.define do |b|
-    ...
-  end
-</pre>
+{{{lang=ruby,number=true,caption=Creating a registry with #define
+registry = Needle::Registry.define do |b|
+  ...
+end
+}}}
 This block accepts a single parameter--a "builder" object to aid in registering services--and evaluates the block as if it were passed to @Registry#define@ (see below).

data/doc/manual/parts/02_namespaces.txt CHANGED

@@ -6,51 +6,51 @@ Namespaces allow you to organize your services. The feature has many different a
 Creating a namespace is as easy as invoking the @#namespace@ method of the registry (or of another namespace):
-<pre>
-  registry.namespace :stuff
-</pre>
+{{{lang=ruby,caption=Creating a namespace
+registry.namespace :stuff
+}}}
 This would create a new namespace in the registry called @:stuff@. The application may then proceed to register services inside that namespace:
-<pre>
-  registry.stuff.register( :foo ) { Bar.new }
-  ...
-  svc = registry.stuff.foo
-</pre>
+{{{lang=ruby,number=true,caption=Registering services in a namespace
+registry.stuff.register( :foo ) { Bar.new }
+...
+svc = registry.stuff.foo
+}}}
 Here's a tip: _namespaces are just a special kind of service._ This means that you can access namespaces in the same ways that you can access services:
-<pre>
-  svc = registry[:stuff][:foo]
-</pre>
+{{{lang=ruby,caption=Accessing a namespace
+svc = registry[:stuff][:foo]
+}}}
 h3. Convenience Methods
 Because it is often the case that you will be creating a namespace and then immediately registering services on it, you can pass a block to @namespace@. The block will receive a reference to the new namespace:
-<pre>
-  registry.namespace :stuff do |spc|
-    spc.register( :foo ) { Bar.new }
-    ...
-  end
-</pre>
+{{{lang=ruby,number=true,caption=More registering services in a namespace
+registry.namespace :stuff do |spc|
+  spc.register( :foo ) { Bar.new }
+  ...
+end
+}}}
 If you prefer the @define@ approach to registering services, you may like @namespace_define@, which creates the new namespace and immediately calls @define@ on it:
-<pre>
-  registry.namespace_define :stuff do |b|
-    b.foo { Bar.new }
-    ...
-  end
-</pre>
+{{{lang=ruby,number=true,caption=Creating namespaces with #namespace_define
+registry.namespace_define :stuff do |b|
+  b.foo { Bar.new }
+  ...
+end
+}}}
 And, to mirror the @namespace_define@ method, there is also a @namespace_define!@ method. This method creates a new namespace and then does a @define!@ call on that namespace.
-<pre>
-  registry.namespace_define! :stuff do
-    foo { Bar.new }
-    ...
-  end
-</pre>
+{{{lang=ruby,number=true,caption=Creating namespaces with #namespace_define!
+registry.namespace_define! :stuff do
+  foo { Bar.new }
+  ...
+end
+}}}
 The above code would create a new namespace called @:stuff@ in the registry, and would then proceed to register a service called @:foo@ in the new namespace.

data/doc/manual/parts/02_services.txt CHANGED

@@ -1,20 +1,20 @@
 Registering services with a Needle registry is very straightforward. The simplest way to do it is:
-<pre>
-  registry.register( :foo ) { Bar.new }
-</pre>
+{{{lang=ruby,caption=Registering services
+registry.register( :foo ) { Bar.new }
+}}}
 The above will register a new service with the registry, naming it @:foo@. When @:foo@ is requested from the registry, a new instance of @Bar@ will be instantiated and returned.
 You get services from the registry in either of two ways:
-<pre>
-  # Treating the registry as a Hash
-  svc = registry[:foo]
+{{{lang=ruby,number=true,caption=Accessing services
+# Treating the registry as a Hash
+svc = registry[:foo]
-  # Treating the service as a property of the registry
-  svc = registry.foo
-</pre>
+# Treating the service as a property of the registry
+svc = registry.foo
+}}}
 h3. Convenience Methods
@@ -22,36 +22,36 @@ Because you will often need to register many services with a registry at once, t
 The first is @define@. Just pass a block to define that accepts one parameter. This parameter will be a "builder" object that allows you to define services just by sending them as messages to the builder:
-<pre>
-  registry.define do |b|
-    b.foo { Bar.new }
-    b.bar { Foo.new }
-    ...
-  end
-</pre>
+{{{lang=ruby,number=true,caption=Defining services
+registry.define do |b|
+  b.foo { Bar.new }
+  b.bar { Foo.new }
+  ...
+end
+}}}
 Alternative, you can call @define!@, passing a block that accepts no parameters. This block will be evaluated in the "builder" object's context, with any unrecognized method call being interpreted as a new service registration of that name:
-<pre>
-  registry.define! do
-    foo { Bar.new }
-    bar { Foo.new }
-    ...
-  end
-</pre>
+{{{lang=ruby,number=true,caption=Defining services via #define!
+registry.define! do
+  foo { Bar.new }
+  bar { Foo.new }
+  ...
+end
+}}}
 Both of the above will register two new services with the registry, @:foo@ and @:bar@.
-h3. Default Lifecycle
+h3. Default Lifestyle
 By default, a service is only instantiated once per registry. This means that (using the above example) if the service @:foo@ were queried twice, the registry would return the same object for both queries:
-<pre>
-  svc1 = registry.foo
-  svc2 = registry.foo
+{{{lang=ruby,number=true,caption=Demonstrating singleton service behavior
+svc1 = registry.foo
+svc2 = registry.foo
-  p svc1.object_id == svc2.object_id #=> true
-</pre>
+p svc1.object_id == svc2.object_id #=> true
+}}}
 You can change this behavior, with _service models_. See the chapter on Service Models for more information.
@@ -61,14 +61,14 @@ Needle also supports _parameterized services_. These are services that, when req
 Consider the following example, in which some hypothetical @Printer@ class represents any of a number of printers, based on a parameter given to its constructor.
-<pre>
-  registry.register( :printer, :model => :multiton ) do |c,p,name|
-    Printer.new( c.log_for( p ), name )
-  end
+{{{lang=ruby,number=true,caption=Parameterized services
+registry.register( :printer, :model => :multiton ) do |c,p,name|
+  Printer.new( c.log_for( p ), name )
+end
-  mono  = registry.printer( :monochrome )
-  color = registry.printer( :color )
-</pre>
+mono  = registry.printer( :monochrome )
+color = registry.printer( :color )
+}}}
 There are a few things to note about the above example:
@@ -80,10 +80,9 @@ There are a few things to note about the above example:
 # See how the printer service is requested on the last two lines. In this case, the @#printer@ message is sent to the registry with a single parameter. You can also request the service in two other ways:
-<pre>
-  dot_matrix = registry[ :printer, :dot_matrix ]
-  ink_jet    = registry.get( :printer, :ink_jet )
-</pre>
+{{{lang=ruby,number=true,caption=Accessing parameterized services
+dot_matrix = registry[ :printer, :dot_matrix ]
+ink_jet    = registry.get( :printer, :ink_jet )
+}}}
 Choose the style that works best for you.