commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hls...@apache.org
Subject cvs commit: jakarta-commons-sandbox/hivemind/xdocs override.xml navigation.xml
Date Tue, 09 Sep 2003 22:09:21 GMT
hlship      2003/09/09 15:09:21

  Modified:    hivemind/xdocs navigation.xml
  Added:       hivemind/xdocs override.xml
  Log:
  Add doc on how to override services.
  
  Revision  Changes    Path
  1.17      +2 -1      jakarta-commons-sandbox/hivemind/xdocs/navigation.xml
  
  Index: navigation.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/hivemind/xdocs/navigation.xml,v
  retrieving revision 1.16
  retrieving revision 1.17
  diff -u -r1.16 -r1.17
  --- navigation.xml	8 Sep 2003 23:07:22 -0000	1.16
  +++ navigation.xml	9 Sep 2003 22:09:21 -0000	1.17
  @@ -23,6 +23,7 @@
   			<item name="Localization" href="/localization.html"/>
   			<item name="Inversion of Control" href="/ioc.html"/>
   			<item name="Multi-Threading" href="/multithreading.html"/>
  +			<item name="Overriding Services" href="/override.html"/>
   			<item name="Case Study #1: Vista Startup/Shutdown"
   				href="case1.html"/>
   		</menu>
  
  
  
  1.1                  jakarta-commons-sandbox/hivemind/xdocs/override.xml
  
  Index: override.xml
  ===================================================================
  <?xml version="1.0"?>
  <!-- $Id: override.xml,v 1.1 2003/09/09 22:09:21 hlship Exp $ -->
  <!DOCTYPE document [
  	<!ENTITY % common-links SYSTEM "../common/links.xml">
  	%common-links;
  	]>
  <document>
  	<properties>
  		<title>Overriding a Service</title>
  		<author email="hlship@apache.org">Howard M. Lewis Ship</author>
  	</properties>
  	<body>
  
  <section name="Introduction">
  
  <p>
  It is not uncommon to want to override an existing service and replace it with a new implementation.
This
  goes beyond simply intercepting the service ... the goal is to replace the original implementation
with
  a new implementation. This occurs frequently in <a href="http://jakarta.apache.org/tapestry/">Tapestry</a>
  where frequently an existing service is replaced with a new implementation that handles
application-specific cases (and
  delegates most cases to the default implementation).
  </p>
  
  <blockquote>
  Note: Tapestry 3.0 is in beta at the time of this writing, and doesn't use HiveMind. Plans
are afoot to 
  refactor Tapestry 3.1 to make considerable use of HiveMind. Many of the ideas represented
in HiveMind
  germinated in earlier Tapestry releases.	
  </blockquote>
  
  <p>
  HiveMind doesn't have an explicit mechanism for accomplishing this ... that's because its
reasonable to
  replace and wrap existing services just with the mechanisms already available.	
  </p>
  
  </section>
  
  
  <section name="Step One: A non-overridable service">
  	
  <p>
  To describe this technique, we'll start with a ordinary, every day service.  In fact, for
  discussion purposes, there will be two services: Consumer and Provider.  Ultimately, we'll
show how to
  override Provider.	  Also for discussion purposes, we'll do all of this in a single module,
though
  (of course) you can as easily split it up across many modules.
  </p>	
  
  <p>
  To begin, we'll define the two services, and set Provider as a property of Consumer:
  <source><![CDATA[
  <?xml version="1.0"?>
  <module id="ex.override" version="1.0.0">
    <service id="Provider" interface="ex.override.Provider">
      <create-instance class="ex.override.impl.ProviderImpl"/>
    </service>
    
    <service id="Consumer" interace="ex.override.Consumer">
      <invoke-factory service-id="hivemind.BuilderFactory">
        <construct class="ex.override.impl.Consumer">
          <set-service property="provider" service-id="Provider"/>
        </construct>
      </invoke-factory>
    </service>
  </module>
  ]]>	
  </source>	
  </p>
  
  </section>
  
  <section name="Step Two: Add some indirection">
  
  <p>
  In this step, we still have just the two services ... Consumer and Provider, but they are
  linked together less explicitly, by using substitution symbols.
  <source><![CDATA[
  <?xml version="1.0"?>
  <module id="ex.override" version="1.0.0">
    <service id="Provider" interface="ex.override.Provider">
      <create-instance class="ex.override.impl.ProviderImpl"/>
    </service>
    
    <extension point-id="hivemind.FactoryDefaults">
      <default symbol="ex.override.Provider" value="ex.override.Provider"/>
    </extension>
    
    <service id="Consumer" interace="ex.override.Consumer">
      <invoke-factory service-id="hivemind.BuilderFactory">
        <construct class="ex.override.impl.Consumer">
          <set-service property="provider" service-id="${ex.override.Provider}"/>
        </construct>
      </invoke-factory>
    </service>
  </module>
  ]]>	
  </source>	
  </p>	
  
  <p>
  The end result is the same ... the symbol <code>ex.override.Provider</code>
 evaluates
  to the service id <code>ex.override.Provider</code> and the end result is the
same as step one.
  We needed to use a fully qualified service id because, ultimately, we don't know in which
modules
  the symbol will be referenced.
  </p>
  
  	
  </section>
  
  <section name="Step Three: Override!">
  	
  
  <p>
  The final step is to define a second service and slip it into place. For kicks, the OverrideProvider
  service will get a reference to the original Provider service.
  <source><![CDATA[
  <?xml version="1.0"?>
  <module id="ex.override" version="1.0.0">
    <service id="Provider" interface="ex.override.Provider">
      <create-instance class="ex.override.impl.ProviderImpl"/>
    </service>
    
    <extension point-id="hivemind.FactoryDefaults">
      <default symbol="ex.override.Provider" value="ex.override.Provider"/>
    </extension>
    
    <service id="OverrideProvider" interface="ex.override.Provider">
      <invoke-factory service-id="hivemind.BuilderFactory">
        <construct class="ex.override.impl.OverrideProviderImpl">
          <set-service property="defaultProvider" service-id="Provider"/>
        </construct>
      </invoke-factory>
    </service>
    
    <extension point-id="hivemind.ApplicationDefaults">
      <default symbol="ex.override.Provider" value="ex.override.OverrideProvider"/>
    </extension>  
    
    <service id="Consumer" interace="ex.override.Consumer">
      <invoke-factory service-id="hivemind.BuilderFactory">
        <construct class="ex.override.impl.Consumer">
          <set-service property="provider" service-id="${ex.override.Provider}"/>
        </construct>
      </invoke-factory>
    </service>
  </module>
  ]]>	
  </source>	
  	
  </p>
  
  <p>
  The new service, OverrideProvider, gets a reference to the original service using its
  real id.  It can't use the symbol that the Consumer service uses, because that would end
up pointing
  it at itself.	Again, in this example it's all happening in a single module, but it could
absolutely be split
  up, with OverrideProvider and the extension to <code>hivemind.ApplicationDefaults</code>
in an entirely
  different module.
  </p>
  
  <p>
  <code>hivemind.ApplicationDefaults</code>	overrides <code>hivemind.FactoryDefaults</code>.

  This means that the Consumer
  will be connected to <code>ex.override.OverrideProvider</code>.
  </p>
  
  <p>
  Note that the &_service; for the Consumer doesn't change between steps two and three.
  </p>
  
  </section>
  
  <section name="Limitations">
  	
  <p>
  The main limitation to this approach is that you can only do it once for a service; there's
no
  way to add an EvenMoreOverridenProvider service that wraps around OverrideProvider (that
wraps around Provider).
  Making multiple contributions to the <code>hivemind.ApplicationDefaults</code>
 extension point
  with the name symbol name will result in a runtime error ... and unpredictable results.
  </p>
  
  <p>
  This could be addressed by adding another <code>SymbolSource</code> (<code>hivemind.ApplicationDefaults</code>
and
  <code>hivemind.FactoryDefaults</code> are <code>SymbolSource</code>s).

  </p>
  
  <p>
  To be honest, if this kind of indirection becomes extremely frequent, then HiveMind should
change
  to accomadate the pattern, perhaps adding an <code>&lt;override&gt;</code>
element, similar to a &_interceptor; element.	
  </p>
  
  </section>
  
  </body>
  </document>
  
  

Mime
View raw message