idregistry 0.1.0

data/History.rdoc

@@ -0,0 +1,3 @@
+=== 0.1.0 / 2012-08-01
+
+* Initial release

data/IDRegistry.rdoc

@@ -0,0 +1,180 @@
+= IDRegistry
+
+IDRegistry is a generic object generator and identity map for Ruby.
+
+This document provides an in-depth introduction to using IDRegistry. For a quick introduction, see the README.
+
+== Identity Maps and Registries
+
+IDRegistry combines two patterns from Martin Fowler's book "Patterns of Enterprise Application Architecture": the Identity Map pattern and the Registry pattern.
+
+An Identity Map is essentially an in-memory cache that references objects based on a unique identifier. Whenever you want to obtain an object, you first check the cache to see if the object already exists---technically, if the cache contains an object for the given unique identifier. If so, you pull that existing instance directly from the cache. Otherwise, you construct the object, making any necessary database calls, and then insert it into the cache. It has now effectively been memoized, and the next time you request that identifier, that same instance will be returned again from the cache.
+
+In addition to the performance benefits of a cache, an Identity Map also ensures that at most one copy of any object will exist in your system at any time. This effectively eliminates a whole class of bugs that could arise if you construct multiple copies of an object whose states get out of sync with each other.
+
+Identity Map is a highly useful pattern, but by itself it tends to be cumbersome to implement. This is because you have to find every point in the code that constructs a model object, and inject some code to manage the cache. To solve this, we combine it with the Registry pattern. A Registry is simply a central source for object procurement; any code that wants to obtain a model object must get it from the Registry. The Registry knows how to construct the object if needed. Thus, it is able to encapsulate the Identity Map logic, providing a one-stop solution for object procurement with caching and duplication elimination. This combination is what we call an IDRegistry.
+
+== Tuples and Patterns
+
+A common practice is to use database primary keys as the unique identifiers for an Identity Map. However, if you are managing multiple kinds of objects, objects that span multiple tables or aren't associated with any particular database row, or objects that otherwise need to be identified across more than one dimension, you need a more versatile unique identifier.
+
+IDRegistry uses arrays, or <i>tuples</i> as we will call them, as unique identifiers. This allows us to support a wide variety of identification strategies. A simple example is to employ a two-element tuple: the first element being a type indicator, and the second being a database primary key. For example, suppose your application had two types of entities: users and blog posts. Your user objects could employ unique identifiers of the form <tt>[:user, <i>user-id</i>]</tt>, and your post objects could employ identifiers of the form <tt>[:post, <i>post-id</i>]</tt>. So the tuple <tt>[:user, 1]</tt> identifies the user with ID 1, and the tuple <tt>[:post, 210]</tt> identifies the post with ID 210.
+
+Such "forms" of tuples that correspond to "types" of objects, we denote as <i>patterns</i>. A pattern is an array like a tuple, but some of its elements are placeholders rather than values. For example, <tt>[:user, 1]</tt> is a tuple that identifies the particular user with ID 1, while <tt>[:user, Integer]</tt> is the pattern followed by user identifiers. The <tt>Integer</tt> element is a placeholder that matches certain kinds of values---in this case, integer IDs. Similarly, <tt>[:post, Integer]</tt> is the pattern followed by blog post identifiers.
+
+It is also common to use <tt>String</tt> as a placeholder element used in patterns. For example, if you have contacts that should be identified by a unique phone number, you could use tuples with the pattern <tt>[:contact, String]</tt> where the unique phone number is represented as a string.
+
+Indeed, technically, a placeholder element can be any object that responds appropriately to the === operator. In most cases, these will be class or module objects such as <tt>Integer</tt> or <tt>String</tt> above; however, patterns can utilize regular expressions, or any other object that classifies based on the === operator.
+
+Additionally, tuples (and patterns) can be longer and more complex than the two-element examples above. Suppose you have objects that represent relationships between users in a social network. Each relationship might be identified by the two user IDs of the users involved. Correspondingly, your identifier tuples might follow the pattern <tt>[:relationship, Integer, Integer]</tt>.
+
+== Basic IDRegistry usage
+
+Creating an IDRegistry is as simple as calling the <tt>create</tt> method:
+
+ my_registry = IDRegistry.create
+
+The job of an IDRegistry is to procure objects by either returning a cached object or creating a new one. Thus, it needs to know how to construct your model objects. You accomplish this by configuring the registry at application initialization time, telling it how to construct the various types of objects it needs to manage.
+
+In the previous section, we saw how a "type" of object can be identified with a <i>pattern</i>. Through configuration, we "teach" an IDRegistry how to construct objects for a given pattern. For example, our user objects have identifiers matching the pattern <tt>[:user, Integer]</tt>. We can configure a registry as follows:
+
+ my_registry.config.add_pattern |pattern|
+   pattern.pattern [:user, Integer]
+   pattern.to_generate_object do |tuple|
+     my_create_user_object_given_id(tuple[1])
+   end
+ end
+
+The <tt>add_pattern</tt> configuration command teaches the IDRegistry about a certain pattern. If the registry encounters a tuple identifier matching that pattern, it specifies how to construct the object given that tuple.
+
+You can add any number of pattern configurations to a registry, covering any number of object types.
+
+Once you have configured your IDRegistry, using it is simple. Call the <tt>lookup</tt> method to obtain an object given a tuple. The registry will check its cache and return the object, or it will invoke the matching pattern configuration to create it.
+
+ user1 = my_registry.lookup(:user, 1)   # constructs a user object
+ user1a = my_registry.lookup(:user, 1)  # returns the same user object
+
+If you want to clear the cache and force the registry to construct new objects, use the <tt>clear</tt> method:
+
+ my_registry.clear
+
+== Multiple identifiers for an object
+
+Sometimes there will be several different mechanisms for identifying an object to procure. Consider a tree stored in the database, in which each node has a name that is unique among its siblings. Now, each node might have a database primary key, so you could identify objects using the pattern <tt>[:node, Integer]</tt>. However, since the combination of parent and name is unique, you could also uniquely identify objects using that combination: <tt>[:node, Integer, String]</tt> for parent ID and child name. These two patterns represent two different ways of looking up a tree node:
+
+ object = find_tree_node_id(id)
+ object = find_tree_from_parent_id_and_child_name(parent_id, child_name)
+
+These two ways to lookup the object correspond to two different tuples---two different unique identifiers. In a simple Identity Map, this would not work. It might create an object using the first identifier, and then create a second object using the second identifier, even if semantically they should be the same object.
+
+IDRegistry, however, supports this case by giving you the ability to define multiple patterns and associate them with the same object type. Here's how.
+
+ my_registry.config do |config|
+   config.add_pattern do |pattern|
+     pattern.type :treenode
+     pattern.pattern [:node, Integer]
+     pattern.to_generate_object do |tuple|
+       find_tree_node_id(tuple[1])
+     end
+     pattern.to_generate_tuple do |obj|
+       [:node, obj.id]
+     end
+   end
+   config.add_pattern do |pattern|
+     pattern.type :treenode
+     pattern.pattern [:node, Integer, String]
+     pattern.to_generate_object do |tuple|
+       find_tree_from_parent_id_and_child_name(tuple[1], tuple[2])
+     end
+     pattern.to_generate_tuple do |obj|
+       [:node, obj.parent_id, obj.name]
+     end
+   end
+ end
+
+Let's unpack this. First, notice that we are now specifying a "type" for each pattern. The type is a name for this type of object. If you omit it (as we did earlier), IDRegistry treats each pattern as a separate anonymous type. In this case, however, we set it explicitly. This lets us specify that both patterns describe the same type of object, a tree node object. Each tree node will now have TWO identifiers, one of each pattern. Doing a lookup for either identifiers will return the same object.
+
+Second, now in addition to the <tt>to_generate_object</tt> block, we now provide a <tt>to_generate_tuple</tt> block. We need to tell IDRegistry how to generate a tuple (identifier) from an object. Why?
+
+Well, suppose were were to look up a tree node by ID:
+
+ # Look up a node by database ID
+ node = my_registry.lookup(:node, 10)
+
+At this point, IDRegistry can cache the object and associate it with the tuple <tt>[:node, 10]</tt> so that you can look it up using that tuple again. However, that object also has a parent and a name (suppose the parent ID is 9 and the name is "foo"). This means we would like to be able to look up that _same_ object using the tuple <tt>[:node, 9, "foo"]</tt>.
+
+ # Should the same object as the original node
+ node1 = my_registry.lookup(:node, node.parent_id, node.name)
+
+IDRegistry therefore needs you to teach it how to generate that other tuple for the object. Similarly, if you originally looked up the tree node by parent ID and name, IDRegistry needs you to teach it how to generate the corresponding simple ID tuple.
+
+So to summarize... if you have only one way to look up an object, you can simply specify the pattern and a <tt>to_generate_object</tt> block. For objects that can be looked up in more than one way, you should also include a type, to connect the various patterns together, and a <tt>to_generate_tuple</tt> block, which tells IDRegistry how to generate missing tuples.
+
+== Categories
+
+Identity maps generally support one-to-one correspondence between objects and unique identifiers. We have already seen how IDRegistry can support multiple identifiers for an object, for object types that require multiple modes of lookup. In this section, we cover categories, which are special identifiers that can reference zero, one, or multiple objects that are already present in the identity map. IDRegistry can look up the collection of objects that match a given category, or use categories to delete groups of objects out of the identity map quickly.
+
+We'll cover an example. Take the "tree node" object type that we covered earlier. One of the patterns for a tree node identifies the node by parent ID and child name: <tt>[:tree, Integer, String]</tt>. This pattern lets us look up a _specific_ child of a given node. However, suppose we want _all_ the children (that have been loaded into the identity map so far) of a given parent. Somehow, we want to provide a specific parent ID, but a wildcard for the name.
+
+That is how categories are defined. We start with an identifier pattern such as our example <tt>[:tree, Integer, String]</tt>. Now we choose some number (zero or more) of the placeholder elements that we want to _specify_. In this example, we want to specify the parent ID, so we choose array index 1, which is the parent ID in our pattern. We call this sequence of element indexes the "category indexes". In this case, the category indexes are <tt>[1]</tt>. The rest of the placeholders (in our example, array index 2, the child name) will be treated as wildcards.
+
+To define such a category, provide a name, a pattern for identifiers, and an array of category indexes, in the registry's configuration as follows:
+
+ my_registry.config do |config|
+   add_category(:node_parent, [:tree, Integer, String], [1])
+ end
+
+Note that what we've done here is create a _class_ of categories---specifically, the class of categories that include the children of given parent nodes. In order to specify a _particular_ category, we must say _which_ parent node. To do that, we take each of the indexes in the category index array (currently just one) and we assign each a particular value. In our example, suppose we want to specify the particular category with parent ID 9. We assign the value 9 to the first and only category index, and we get the array <tt>[9]</tt>. This new array is what we call the "category spec". It specifies a particular category out of our class, in this case, the category of tree nodes whose parent ID is 9.
+
+To look up nodes by category, for example, you must provide the name of the class of categories, and the category spec indicating which particular category.
+
+ objects = my_registry.objects_in_category(:node_parent, [9])
+
+There are many different ways to specify categories. Sometimes you want a single "one-off" category that isn't part of a class of categories. For example, you could define a category that includes ALL tree node objects like this:
+
+ my_registry.config do |config|
+   add_category(:all_nodes, [:tree, Integer, String], [])
+ end
+
+Note that we set the same pattern but now we have no category indexes. This means, we are not going to specify any parameters in order to identify a particular category. Instead, both parent ID and name string are wildcards, and all tree nodes will fall into the same category. This is still a "class" of categories, but a degenerate one with no parameters. When we want to look up the objects, our category spec is similarly the empty array, since we have no category indexes for which to provide values.
+
+ objects = my_registry.objects_in_category(:all_nodes, [])
+
+Some classes of categories may be parameterized by multiple elements. For example, if we set up a category like this:
+
+ my_registry.config do |config|
+   add_category(:parent_and_name, [:tree, Integer, String], [1, 2])
+ end
+
+Now our category is parameterized by both parent and name. This isn't a very useful class of categories since each will contain at most one element. I show it merely to illustrate that you can have multiple category indexes. So here's how to get all the objects in the "category of objects with parent ID 9 and name foo":
+
+ objects = my_registry.objects_in_category(:parent_and_name, [9, "foo"])
+
+Finally, here is one more example. Suppose you did this:
+
+ my_registry.config do |config|
+   add_category(:named_foo, [:tree, Integer, 'foo'], [])
+ end
+
+Notice that we've replaced the "child name" placeholder with a particular ID. That element is no longer a placeholder, but a specific value. This is now a one-off category (i.e. a degenerate class of categories with no parameters) of objects whose name is "foo". The pattern that you use to define a category doesn't have to be exactly one of the patterns that you use to define an object type. It just has to match actual identifier tuples in your registry.
+
+== Web requests
+
+In a web application, you will typically want to "scope" an identity map to a request. That is, you usually won't want objects from one request leaking into the next. IDRegistry provides two different mechanisms to limit the scope of a registry.
+
+First, if you are certain that only one request will be run at a time in any given process, you can keep a single global registry, and just clean it out at the end of a request. IDRegistry provides a Rack middleware for this purpose. If you are running Rails, you can include a Railtie that installs the middleware for you, and gives you a configuration that you can use to specify which registry to clear.
+
+If you are running multithreaded, then you will need multiple registries, one for each request. The easiest way to do this is to configure a registry as a "template" at startup, and then use the spawn_registry method to create a new empty registry from that template for each request. A Rack middleware that implements this strategy is also provided.
+
+== Thread safety
+
+IDRegistry is fully thread safe. All object lookup and manipulation methods, as well as configuration methods, are re-entrant and can be called concurrently from multiple threads. The desired invariant, that a registry will contain at most one copy of any given object, will be maintained.
+
+There is, however, one caveat that has to do with the callbacks for constructing objects or generating tuples. IDRegistry does not include those callbacks within its critical sections. (To do so would invite deadlocks.) Instead, we run callbacks eagerly and serialize later on insertion. This means it is possible, in a multi-threaded environment, for a callback to be called but its result to be discarded. Here is the scenario:
+
+* Two threads simultaneously call Registry#lookup for the same tuple that is not already present in the identity map.
+* Within IDRegistry, both threads check for the tuple and determine that it is not present.
+* Both threads then call the callback to create the object. Because IDRegistry does not put any mutual exclusion on callbacks, they execute concurrently and create two separate objects.
+* However, only one of the two objects will actually be used. IDRegistry will use the object created by whichever thread finishes first, and throw away the object created by the slower thread. Both threads will return the same object, the first thread's copy, from the call.
+
+Therefore, our desired behavior still holds; however, you should be aware that it is possible for more than one copy of an object to have been created in the interim.

data/README.rdoc

@@ -0,0 +1,185 @@
+= IDRegistry
+
+IDRegistry is a generic object generator and identity map for Ruby.
+
+== Introduction to IDRegistry
+
+An IDRegistry is a hub for obtaining and managing domain objects in a
+Ruby application. It is a configurable general registry for identifying
+and constructing objects when needed, and it includes a built-in identity
+map which caches objects in memory and prevents duplicates.
+
+=== An Example
+
+That's a lot of jargon, so let's clarify with an example. Suppose you
+are writing a Ruby application in which you have user objects and blog
+post objects, each identified by an ID number (which might be the
+primary key in a database.) In effect, you can uniquely identify any of
+these domain objects by a two-element tuple (array), [type, id], where the
+type is one of the symbols <tt>:user</tt> or <tt>:post</tt>, and the id
+is an integer.
+
+An IDRegistry is a central object that lets you obtain any of your
+domain objects by giving it that unique identifying tuple.
+
+ # Get the user with ID 1
+ first_user = registry.lookup(:user, 1)
+ 
+ # Get the user with ID 2
+ second_user = registry.lookup(:user, 2)
+ 
+ # Get the blog post with ID 300
+ post = registry.lookup(:post, 300)
+
+=== Configuration
+
+How does IDRegistry know how to construct your user and post objects?
+At initialization time, you configure IDRegistry, telling it about each
+type of object it will need to manage. For each object type, you provide
+a pattern for the identifying tuple, and a block that constructs a new
+object when needed. Here's an example:
+
+ # Create and configure the registry at initialization time
+ registry = Registry.create do |config|
+ 
+   # The pattern for identifying tuples for user objects
+   config.add_pattern([:user, Integer]) do |tuple|
+     # How to construct a user object given a tuple
+     my_construct_user_object_from_id(tuple[1])
+   end
+ 
+   # The pattern for identifying tuples for post objects
+   config.add_pattern([:post, Integer]) do |tuple|
+     # How to construct a post object given a tuple
+     my_construct_post_object_from_id(tuple[1])
+   end
+ 
+ end
+
+Now, when you ask for a particular tuple, say, [:user, 1], the
+IDRegistry finds the pattern that matches that tuple, and uses it to
+construct and return the appropriate object.
+
+=== Caching
+
+The real power, however, comes from the fact that IDRegistry now
+caches all the objects it creates in an internal hash. So if you ask
+for the same tuple identifier a second time, it doesn't construct a
+second object, but simply returns the same object it had constructed
+earlier. In other words, it has a built-in identity map.
+
+ # Get the user with ID 1
+ first_user = registry.lookup(:user, 1)
+ 
+ # If you re-ask for the same identifier, you get the same object.
+ same_user = registry.lookup(:user, 1)
+ same_user.object_id == first_user.object_id  # => true
+
+You can remove cached objects from the registry, forcing the registry
+to re-construct them the next time you ask for them. A common usage
+pattern in a web application is to clear out the registry cache at the
+end of each request, so that each request is self-contained and has its
+own copies of domain objects. A Rack middleware is provided for this
+purpose.
+
+=== Tuples
+
+Identifying tuples don't have to follow the pattern [type, id]. They
+can actually be any array. For example, you might want to identify
+nodes in a tree using a combination of parent and child name, rather
+than just the ID. For such tree node objects, you might use a pattern
+like <tt>[:tree, Node, String]</tt>, where the second element is
+the parent node itself, and the third is the name of the child.
+
+In fact, it is even possible to provide multiple ways of identifying
+objects. Perhaps you want to be able to look up tree nodes by either
+ID number, or by parent/child-name. In configuration, you can tell
+IDRegistry that these refer to the same type of object. Then, if you
+first look up an object by ID, and then later look up the same object
+by parent/child-name, IDRegistry will be smart enough to know you are
+referring to the same object, and will return its cached data.
+
+=== Why?
+
+IDRegistry is an extraction of an identity map I wrote for a few large
+Rails applications, including the back-end for Pirq (www.pirq.com).
+
+Our model objects were getting quite complex with lots of associations
+and dependencies, and we were having difficulty keeping track of which
+objects had already been loaded, and whether we had multiple copies of
+objects in memory that might be getting out of sync with one another.
+
+After we wrote IDRegistry and refactored our object creation to use it,
+our domain object management code was greatly simplified, and a whole
+class of bugs was eliminated. We've been using it in production for
+several years, and now we offer it to the community.
+
+=== For more info
+
+More detailed info is available in the IDRegistry.rdoc file.
+
+== Dependencies
+
+IDRegistry is known to work with the following Ruby implementations:
+
+* Standard "MRI" Ruby 1.8.7 or later. (1.9.2 or later preferred.)
+* Rubinius 1.1 or later.
+* JRuby 1.6 or later.
+
+== Installation
+
+Install IDRegistry as a gem:
+
+ gem install idregistry
+
+== Development and support
+
+Documentation is available at http://dazuma.github.com/idregistry/rdoc
+
+Source code is hosted on Github at http://github.com/dazuma/idregistry
+
+Contributions are welcome. Fork the project on Github.
+
+Build status: {<img src="https://secure.travis-ci.org/dazuma/idregistry.png" />}[http://travis-ci.org/dazuma/idregistry]
+
+Report bugs on Github issues at http://github.org/dazuma/idregistry/issues
+
+Contact the author at dazuma at gmail dot com.
+
+== Acknowledgments
+
+IDRegistry is written by Daniel Azuma (http://www.daniel-azuma.com).
+
+Development is supported by Pirq (http://www.pirq.com).
+
+Continuous integration service provided by Travis-CI (http://travis-ci.org).
+
+== License
+
+Copyright 2012 Daniel Azuma
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+* Neither the name of the copyright holder, nor the names of any other
+  contributors to this software, may be used to endorse or promote products
+  derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

data/Version

@@ -0,0 +1 @@
+0.1.0

data/lib/idregistry.rb

@@ -0,0 +1,48 @@
+# -----------------------------------------------------------------------------
+#
+# IDRegistry main file
+#
+# -----------------------------------------------------------------------------
+# Copyright 2012 Daniel Azuma
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the copyright holder, nor the names of any other
+#   contributors to this software, may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+# -----------------------------------------------------------------------------
+;
+
+
+# IDRegistry is a generic object generator and identity map for Ruby.
+
+module IDRegistry
+end
+
+
+require 'idregistry/version'
+require 'idregistry/utils'
+require 'idregistry/errors'
+require 'idregistry/configuration'
+require 'idregistry/registry'
+require 'idregistry/middleware'

data/lib/idregistry/configuration.rb

@@ -0,0 +1,523 @@
+# -----------------------------------------------------------------------------
+#
+# IDRegistry configuration object
+#
+# -----------------------------------------------------------------------------
+# Copyright 2012 Daniel Azuma
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the copyright holder, nor the names of any other
+#   contributors to this software, may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+# -----------------------------------------------------------------------------
+;
+
+
+require 'blockenspiel'
+
+
+module IDRegistry
+
+
+  # A registry configuration.
+  #
+  # Access this API by calling the configuration method of a registry.
+  # Conceptually, the configuration and the registry are just two
+  # windows (APIs) into the same object.
+  #
+  # Once objects are added to the registry, the configuration is locked
+  # and cannot be modified. Informational methods may still be called.
+
+  class Configuration
+
+    include ::Blockenspiel::DSL
+
+    dsl_methods false
+
+
+    # Object types that aren't explicitly provided will be assigned
+    # anonymous types that are instances of this class.
+
+    class AnonymousType; end
+
+
+    def initialize(registry_, patterns_, types_, categories_, methods_)  # :nodoc:
+      @registry = registry_
+      @patterns = patterns_
+      @types = types_
+      @categories = categories_
+      @methods = methods_
+      @locked = false
+      @mutex = ::Mutex.new
+    end
+
+
+    def inspect  # :nodoc:
+      "#<#{self.class}:0x#{object_id.to_s(16)}>"
+    end
+
+
+    # Returns true if this configuration has been locked.
+    # A locked configuration can no longer be modified.
+    # Registries lock their configurations once you start using them.
+
+    def locked?
+      @locked
+    end
+
+
+    # Returns the registry that owns this configuration.
+
+    def registry
+      @registry
+    end
+
+
+    # Create a new empty registry, duplicating this configuration.
+    #
+    # If the <tt>:unlocked</tt> option is set to true, the new registry
+    # will have an unlocked configuration that can be modified further.
+    # Otherwise, the new registry's configuration will be locked.
+    #
+    # Spawning a locked registry from a locked configuration is very fast
+    # because it reuses the configuration objects.
+
+    def spawn_registry(opts_={})
+      request_unlocked_ = opts_[:unlocked]
+      if @locked && !request_unlocked_
+        reg_ = Registry._new(@patterns, @types, @categories, @methods)
+        reg_.config.lock
+      else
+        patterns_ = {}
+        types_ = {}
+        categories_ = {}
+        methods_ = {}
+        @mutex.synchronize do
+          @patterns.each{ |k_, v_| patterns_[k_] = v_.dup }
+          @types.each{ |k_, v_| types_[k_] = v_.dup }
+          @categories.each{ |k_, v_| categories_[k_] = v_.dup }
+          @methods.each{ |k_, v_| methods_[k_] = v_.dup }
+        end
+        reg_ = Registry._new(patterns_, types_, categories_, methods_)
+        reg_.config.lock unless request_unlocked_
+      end
+      reg_
+    end
+
+
+    dsl_methods true
+
+
+    # Lock the configuration, preventing further changes.
+    #
+    # This is called by registries when you start using them.
+    #
+    # In addition, it is cheap to spawn another registry from a
+    # configuration that is locked, because the configuration internals
+    # can be reused. Therefore, you should lock a configuration if you
+    # want to use it as a template to create empty registries quickly
+    # (using the spawn_registry call).
+
+    def lock
+      @mutex.synchronize do
+        @locked = true
+      end
+      self
+    end
+
+
+    # Returns an array of all patterns known by this configuration.
+    #
+    # The pattern arrays will be duplicates of the actual arrays
+    # stored internally, so you cannot modify patterns in place.
+
+    def all_patterns
+      @mutex.synchronize do
+        @patterns.keys.map{ |a_| a_.dup }
+      end
+    end
+
+
+    # Returns an array of all object types known by this configuration.
+    #
+    # Does not include any "anonymous" types that are automatically
+    # generated if you add a pattern without a type.
+
+    def all_types
+      @mutex.synchronize do
+        @types.keys.find_all{ |t_| !t_.is_a?(AnonymousType) }
+      end
+    end
+
+
+    # Returns an array of all category types known by this configuration.
+
+    def all_categories
+      @mutex.synchronize do
+        @categories.keys
+      end
+    end
+
+
+    # Returns an array of all convenience method names known by this
+    # configuration.
+
+    def all_convenience_methods
+      @mutex.synchronize do
+        @methods.keys
+      end
+    end
+
+
+    # Returns true if this configuration includes the given pattern.
+
+    def has_pattern?(pattern_)
+      @mutex.synchronize do
+        @patterns.has_key?(pattern_)
+      end
+    end
+
+
+    # Returns true if this configuration includes the given object type.
+
+    def has_type?(type_)
+      @mutex.synchronize do
+        @types.has_key?(type_)
+      end
+    end
+
+
+    # Returns true if this configuration includes the given category type.
+
+    def has_category?(category_)
+      @mutex.synchronize do
+        @categories.has_key?(category_)
+      end
+    end
+
+
+    # Returns true if this configuration includes the given convenience method.
+
+    def has_convenience_method?(method_)
+      @mutex.synchronize do
+        @methods.has_key?(method_)
+      end
+    end
+
+
+    # Returns the object type corresponding to the given pattern.
+    # Returns nil if the given pattern is not recognized.
+
+    def type_for_pattern(pattern_)
+      @mutex.synchronize do
+        patdata_ = @patterns[pattern_]
+        patdata_ ? patdata_[0] : nil
+      end
+    end
+
+
+    # Returns an array of patterns corresponding to the given object type.
+    # Returns the empty array if the given object type is not recognized.
+
+    def patterns_for_type(type_)
+      @mutex.synchronize do
+        typedata_ = @types[type_]
+        typedata_ ? typedata_.dup : []
+      end
+    end
+
+
+    # Add a pattern to the configuration.
+    #
+    # You may use one of the following call sequences:
+    #
+    # [<tt>add_pattern( <i>pattern</i> ) { ... }</tt>]
+    #   Add a simple pattern, using the given block to generate objects
+    #   matching that pattern.
+    #
+    # [<tt>add_pattern( <i>pattern</i>, <i>to_generate_object</i> )</tt>]
+    #   Add a simple pattern, using the given proc to generate objects
+    #   matching that pattern.
+    #
+    # [<tt>add_pattern( <i>pattern</i>, <i>to_generate_object</i>, <i>to_generate_tuple</i> )</tt>]
+    #   Add a simple pattern, using the given proc to generate objects
+    #   matching that pattern, and to generate a tuple from an object.
+    #
+    # [<tt>add_pattern( <i>pattern</i>, <i>type</i>, <i>to_generate_object</i>, <i>to_generate_tuple</i> )</tt>]
+    #   Add a pattern for the given type. You should provide both a proc
+    #   to generate objects, and a proc to generate a tuple from an object.
+    #
+    # [<tt>add_pattern() { ... }</tt>]
+    #   Utilize a PatternAdder DSL to define the pattern.
+
+    def add_pattern(*args_, &block_)
+      raise ConfigurationLockedError if @locked
+      if block_
+        case args_.size
+        when 0
+          adder_ = PatternAdder._new(nil, nil, nil, nil)
+          ::Blockenspiel.invoke(block_, adder_)
+        when 1
+          adder_ = PatternAdder._new(args_[0], nil, block_, nil)
+        else
+          raise IllegalConfigurationError, "Did not recognize call sequence for add_pattern"
+        end
+      else
+        case args_.size
+        when 2, 3
+          adder_ = PatternAdder._new(args_[0], nil, args_[1], args_[2])
+        when 4
+          adder_ = PatternAdder._new(args_[0], args_[1], args_[2], args_[3])
+        else
+          raise IllegalConfigurationError, "Did not recognize call sequence for add_pattern"
+        end
+      end
+      pattern_ = adder_.pattern
+      type_ = adder_.type || AnonymousType.new
+      gen_obj_ = adder_.to_generate_object
+      gen_tuple_ = adder_.to_generate_tuple
+      @mutex.synchronize do
+        raise ConfigurationLockedError if @locked
+        if @patterns.has_key?(pattern_)
+          raise IllegalConfigurationError, "Pattern already exists"
+        end
+        @patterns[pattern_] = [type_, gen_obj_, gen_tuple_]
+        (@types[type_] ||= []) << pattern_
+      end
+      self
+    end
+
+
+    # Remove the given pattern from this configuration.
+    # Automatically removes the object type if this is the object type's
+    # only remaining pattern.
+
+    def delete_pattern(pattern_)
+      @mutex.synchronize do
+        raise ConfigurationLockedError if @locked
+        if (patdata_ = @patterns.delete(pattern_))
+          type_ = patdata_[0]
+          typedata_ = @types[type_]
+          typedata_.delete(pattern_)
+          @types.delete(type_) if typedata_.empty?
+        end
+      end
+      self
+    end
+
+
+    # Remove the given object type from this configuration.
+    # Automatically removes all patterns associated with this object type.
+
+    def delete_type(type_)
+      @mutex.synchronize do
+        raise ConfigurationLockedError if @locked
+        if (typedata_ = @types.delete(type_))
+          typedata_.each{ |pat_| @patterns.delete(pat_) }
+        end
+      end
+      self
+    end
+
+
+    # Add a category type.
+    #
+    # You must provide a category type name, a pattern that recognizes
+    # tuples that should trigger this category, and an array of indexes
+    # into the pattern that indicates which tuple element(s) will
+    # identify individual categories within this category type.
+
+    def add_category(category_, pattern_, indexes_=[])
+      @mutex.synchronize do
+        raise ConfigurationLockedError if @locked
+        if @categories.has_key?(category_)
+          raise IllegalConfigurationError, "Category already exists"
+        end
+        @categories[category_] = [pattern_, indexes_]
+      end
+      self
+    end
+
+
+    # Remove a category type by name.
+
+    def delete_category(category_)
+      @mutex.synchronize do
+        raise ConfigurationLockedError if @locked
+        @categories.delete(category_)
+      end
+      self
+    end
+
+
+    # Add a convenience method, providing a short cut for doing lookups
+    # in the registry. You must provide a pattern that serves as a tuple
+    # template, and an array of indexes. The method will take a number of
+    # arguments corresponding to that array, and the indexes will then be
+    # used as indexes into the pattern, replacing pattern elements to
+    # generate the actual tuple to be looked up.
+
+    def add_convenience_method(name_, pattern_, indexes_)
+      @mutex.synchronize do
+        raise ConfigurationLockedError if @locked
+        name_ = name_.to_sym
+        if @methods.has_key?(name_)
+          raise IllegalConfigurationError, "Factory method already exists"
+        end
+        @methods[name_] = [pattern_, indexes_]
+      end
+      self
+    end
+
+
+    # Delete a convenience method by name.
+
+    def delete_convenience_method(name_)
+      @mutex.synchronize do
+        raise ConfigurationLockedError if @locked
+        @methods.delete(name_.to_sym)
+      end
+      self
+    end
+
+
+    # Clear all configuration information, including all object types,
+    # patterns, categories, and convenience methods.
+
+    def clear
+      @mutex.synchronize do
+        raise ConfigurationLockedError if @locked
+        @patterns.clear
+        @types.clear
+        @categories.clear
+        @methods.clear
+      end
+      self
+    end
+
+
+    class << self
+
+      # :stopdoc:
+      alias_method :_new, :new
+      private :new
+      # :startdoc:
+
+    end
+
+
+  end
+
+
+  # This is the DSL available within the block passed to
+  # Configuration#add_pattern.
+
+  class PatternAdder
+
+    include ::Blockenspiel::DSL
+
+    def initialize(pattern_, type_, gen_obj_, gen_tuple_)  # :nodoc:
+      @pattern = pattern_
+      @type = type_
+      @gen_obj = gen_obj_
+      @gen_tuple = gen_tuple_
+    end
+
+
+    def inspect  # :nodoc:
+      "#<#{self.class}:0x#{object_id.to_s(16)}>"
+    end
+
+
+    # Set the pattern to add
+
+    def pattern(value_=nil)
+      if value_
+        @pattern = value_
+      else
+        @pattern
+      end
+    end
+
+
+    # Set the object type
+
+    def type(value_=nil)
+      if value_
+        @type = value_
+      else
+        @type
+      end
+    end
+
+
+    # Provide a block to call to generate the appropriate object given a
+    # tuple. This block is called when the repository is asked to lookup
+    # an object given a tuple, and the provided tuple is not yet present.
+    #
+    # The block may take up to three arguments.
+    # The first is the tuple.
+    # The second is the repository containing the object.
+    # The third is a hash of arguments passed to the repository's lookup
+    # method.
+    #
+    # The block should return the generated object, or nil if it is unable
+    # to generate an object for the given tuple.
+
+    def to_generate_object(&block_)
+      if block_
+        @gen_obj = block_
+      else
+        @gen_obj
+      end
+    end
+
+
+    # Provide a block to call to generate the tuple corresponding to an
+    # object. The repository calls this block when an object is added, in
+    # order to generate the appropriate tuples for looking up the object.
+
+    def to_generate_tuple(&block_)
+      if block_
+        @gen_tuple = block_
+      else
+        @gen_tuple
+      end
+    end
+
+
+    class << self
+
+      # :stopdoc:
+      alias_method :_new, :new
+      private :new
+      # :startdoc:
+
+    end
+
+
+  end
+
+
+end