hivemind-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hls...@apache.org
Subject cvs commit: jakarta-hivemind/src/documentation/content/xdocs index.xml configurations.xml dependencies.xml
Date Tue, 17 Aug 2004 12:33:23 GMT
hlship      2004/08/17 05:33:23

  Modified:    src/documentation/content/xdocs index.xml configurations.xml
                        dependencies.xml
  Log:
  Fix typos and reformat parts of the documentation.
  
  Revision  Changes    Path
  1.16      +101 -116  jakarta-hivemind/src/documentation/content/xdocs/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-hivemind/src/documentation/content/xdocs/index.xml,v
  retrieving revision 1.15
  retrieving revision 1.16
  diff -u -r1.15 -r1.16
  --- index.xml	6 Aug 2004 14:16:41 -0000	1.15
  +++ index.xml	17 Aug 2004 12:33:22 -0000	1.16
  @@ -168,31 +168,23 @@
   				of small parts. HiveDoc is an important tool for developers to
   				understand and debug the application.</p>
   		</section>
  -		<section>
  -			<title>Why should you use HiveMind?</title>
  -			<p>The concept behind HiveMind, and most other microkernels, is to reduce
  -				the amount of code in your application and at the same time, make your
  -				application more testable. If your applications are like my
  -				applications, there is an awful lot of code in place that deals just
  -				with creating objects and hooking them together, and reading and
  -				processing configuration files.</p>
  -			<p>HiveMind moves virtually all of that logic into the framework, driven
  -				by the module deployment descriptors. Inside the descriptor, you
  -				describe your services, your configuration data, and how everything is
  -				hooked together within and between modules.</p>
  -			<p>HiveMind can do all the grunt work for you; using HiveMind makes it so
  -				that <em>the easiest approach is also the correct approach.</em> </p>
  -			<table>
  -				<tr>
  -					<th>Task</th>
  -					<th>Typical Approach</th>
  -					<th>HiveMind Approach</th>
  -				</tr>
  -				<tr>
  -					<td>Log method entry and exit</td>
  -					<td>
  -						<source>
  -							<![CDATA[ 
  +    
  +    <section>
  +      <title>Why should you use HiveMind?</title>
  +      <p>The concept behind HiveMind, and most other dependency-injection microkernels,
is to reduce the amount of code 
  +        in your application and at the same time, make your application more testable.
If your applications are like my 
  +        applications, there is an awful lot of code in place that deals just with creating
objects and hooking them 
  +        together, and reading and processing configuration files.</p>
  +      <p>HiveMind moves virtually all of that logic into the framework, driven by
the module deployment descriptors. 
  +        Inside the descriptor, you describe your services, your configuration data, and
how everything is hooked 
  +        together within and between modules.</p>
  +      <p>HiveMind can do all the grunt work for you; using HiveMind makes it so that
<em>the easiest approach is also 
  +        the correct approach.</em> </p>
  +      <section>
  +        <title>Task: Log method entry and exit</title>
  +        <section>
  +          <title>Typical Approach</title>
  +          <source> <![CDATA[ 
   public String myMethod(String param)
   {
     if (LOG.isDebugEnabled()) 
  @@ -204,28 +196,29 @@
       LOG.debug("myMethod() returns " + result); 
       
     return result;
  -}]]>
  -						</source>
  -						<p>This approach doesn't do a good or consistent job when a method
  -							has multiple return points. It also creates many more branch
  -							points within the code ... basically, a lot of clutter. Finally,
  -							it doesn't report on exceptions thrown from within the method.</p>
  -					</td>
  -					<td>Let HiveMind add a <link href="site:hivemind.LoggingInterceptor">
  -						logging interceptor</link> to your service. It will consistently log
  -						method entry and exit, and log any exceptions thrown by the method. 
  -						<p>The following descriptor snippet defines a service, provides a
  -						core service implementation (using &_create-instance;), and adds
  -						method logging (using &_interceptor;):</p> <source><![CDATA[
  +}]]> </source>
  +          <p>This approach doesn't do a good or consistent job when a method has
multiple return points. It also 
  +            creates many more branch points within the code ... basically, a lot of clutter.
Finally, it doesn't report 
  +            on exceptions thrown from within the method.</p>
  +        </section>
  +        <section>
  +          <title>HiveMind Approach</title>
  +          <p>Let HiveMind add a <link href="site:hivemind.LoggingInterceptor">
logging interceptor</link> to your 
  +            service. It will consistently log method entry and exit, and log any exceptions
thrown by the method.</p>
  +          <p>The following descriptor snippet defines a service, provides a core
service implementation (using 
  +            &_create-instance;), and adds method logging (using &_interceptor;):</p>
  +          <source><![CDATA[
   <service-point id="MyService" interface="com.myco.MyServiceInterface">
     <create-instance class="com.myco.impl.MyServiceImpl"/>
     <interceptor service-id="hivemind.LoggingInterceptor"/>
  -</service-point>]]> </source> </td>
  -				</tr>
  -				<tr>
  -					<td>Reference another service</td>
  -					<td>
  -						<source><![CDATA[
  +</service-point>]]> </source>
  +        </section>
  +      </section>
  +      <section>
  +        <title>Task: Reference another service</title>
  +        <section>
  +          <title>Typical Approach</title>
  +          <source><![CDATA[
   private SomeOtherService _otherService;
   
   public String myMethod(String param)
  @@ -237,18 +230,17 @@
     
     . . .
   }]]> </source>
  -						<p>How the other service is looked up is specified to the
  -							environment; it might be a JNDI lookup for an EJB. For other
  -							microkernels, such as Avalon, there will be calls to a specific
  -							API.</p>
  -						<p>In addition, this code is not thread-safe; multiple threads could
  -							execute it simultaneously, causing unwanted (and possibly
  -							destructive) multiple lookups of the other service.</p>
  -					</td>
  -					<td>Let HiveMind assign the other service as a property. This is <link
  -						href="http://www.martinfowler.com/articles/injection.html">
  -						dependency injection</link>. HiveMind can inject dependencies using
  -						JavaBeans properties or constructor arguments. <source><![CDATA[
  +          <p>How the other service is looked up is specified to the environment;
it might be a JNDI lookup for an EJB. 
  +            For other microkernels, such as Avalon, there will be calls to a specific API.</p>
  +          <p>In addition, this code is not thread-safe; multiple threads could execute
it simultaneously, causing 
  +            unwanted (and possibly destructive) multiple lookups of the other service.</p>
  +        </section>
  +        <section>
  +          <title>HiveMind Approach</title>
  +          <p>Let HiveMind assign the other service as a property. This is <link

  +            href="http://www.martinfowler.com/articles/injection.html"> dependency injection</link>.
HiveMind can 
  +            inject dependencies using JavaBeans properties or constructor arguments.</p>
  +          <source><![CDATA[
   private SomeOtherService _otherService;
   
   public void setOtherService(SomeOtherService otherService)
  @@ -261,27 +253,27 @@
     _otherService.doSomething(. . .);
     
     . . .
  -}]]> </source> <p>HiveMind uses a system of proxies to defer creation of
  -						services until actually needed. The proxy object assigned to the
  -						otherService property will cause the actual service implementation
  -						to be instantiated and configured the first time a service method is
  -						invoked ... and all of this is done in a thread-safe manner.</p> </td>
  -				</tr>
  -				<tr>
  -					<td>Read configuration data</td>
  -					<td>
  -						<p>Find a properties file or XML file (on the classpath? in the
  -							filesystem?) and read it, then write code to intepret the raw data
  -							and possibly convert it to Java objects.</p>
  -						<p>The lack of a standard approach means that data-driven solutions
  -							are often more trouble than they are worth, leading to code bloat
  -							and a loss of flexibility.</p>
  -						<p>Even when XML files are used for configuration, the code that
  -							reads the contents is often inefficient, incompletely tested, and
  -							lacking the kind of error detection built into HiveMind.</p>
  -					</td>
  -					<td>
  -						<source><![CDATA[
  +}]]> </source>
  +          <p>HiveMind uses a system of proxies to defer creation of services until
actually needed. The proxy object 
  +            assigned to the otherService property will cause the actual service implementation
to be instantiated and 
  +            configured the first time a service method is invoked ... and all of this is
done in a thread-safe 
  +            manner.</p>
  +        </section>
  +      </section>
  +      <section>
  +        <title>Task: Read configuration data</title>
  +        <section>
  +          <title>Typical Approach</title>
  +          <p>Find a properties file or XML file (on the classpath? in the filesystem?)
and read it, then write code to 
  +            intepret the raw data and possibly convert it to Java objects.</p>
  +          <p>The lack of a standard approach means that data-driven solutions are
often more trouble than they are 
  +            worth, leading to code bloat and a loss of flexibility.</p>
  +          <p>Even when XML files are used for configuration, the code that reads
the content is often inefficient, 
  +            incompletely tested, and lacking the kind of error detection built into HiveMind.</p>
  +        </section>
  +        <section>
  +          <title>HiveMind Approach</title>
  +          <source><![CDATA[
   private List _configuration;
   
   public void setConfiguration(List configuration)
  @@ -299,44 +291,37 @@
       item.doStuff(. . .);
     }
   }]]> </source>
  -						<p>HiveMind will set the <code>configuration</code> property from
a 
  -							<link href="site:configurations">configuration point</link> you
  -							specify. The objects in the list are constructed from
  -							configuration point contributions and converted, by HiveMind, into
  -							objects. As with services, a thread-safe, just-in-time conversion
  -							takes place.</p>
  -						<p>The type and number of extension points and how and when your
  -							code makes use of them is entirely up to you, configured in the
  -							module deployment descriptor.</p>
  -					</td>
  -				</tr>
  -				<tr>
  -					<td>Test your services</td>
  -					<td>
  -						<p>In complex environments, such as EJB containers, you will often
  -							have to deploy your code and then test it from the outside. EJB
  -							code in particular is hard to test because collaborating EJBs make
  -							use of JNDI to access each other. It is very difficult to "stub
  -							out" part of the overall application for testing purposes.</p>
  -					</td>
  -					<td>
  -						<p>Making code testable is a key concern of HiveMind, and shows up
  -							in its general testing strategy:</p>
  -						<ul>
  -							<li>Because HiveMind services are simply POJOs, your unit tests
  -								can simply instantiate them directly.</li>
  -							<li>HiveMind services are always identified by <em>interface</em>,
  -								so it's easy to provide a mocked-up implementation of the
  -								interface.</li>
  -							<li>Services collaborate via <link href="ioc.html">dependency
  -								injection</link>, so it's easy for a unit test to wire a service
  -								to real or mock implementations of collaborating services.</li>
  -							<li>Because configuration data is just lists of Java objects, unit
  -								tests can easily create objects suitable for testing.</li>
  -						</ul>
  -					</td>
  -				</tr>
  -			</table>
  -		</section>
  +          <p>HiveMind will set the <code>configuration</code> property
from a <link 
  +            href="site:configurations">configuration point</link> you specify.
The objects in the list are constructed 
  +            from configuration point contributions and converted, by HiveMind, into objects.
As with services, a 
  +            thread-safe, just-in-time conversion takes place.</p>
  +          <p>The type and number of extension points and how and when your code makes
use of them is entirely up to 
  +            you, configured in the module deployment descriptor.</p>
  +        </section>
  +      </section>
  +      <section>
  +        <title>Task: Test your services</title>
  +        <section>
  +          <title>Typical Approach</title>
  +          <p>In complex environments, such as EJB containers, you will often have
to deploy your code and then test it 
  +            from the outside. EJB code in particular is hard to test because collaborating
EJBs make use of JNDI to 
  +            access each other. It is very difficult to "stub out" part of the overall application
for testing 
  +            purposes.</p>
  +        </section>
  +        <section>
  +          <title>HiveMind Approach</title>
  +          <p>Making code testable is a key concern of HiveMind, and shows up in its
general testing strategy:</p>
  +          <ul>
  +            <li>Because HiveMind services are simply POJOs, your unit tests can simply
instantiate them directly.</li>
  +            <li>HiveMind services are always identified by <em>interface</em>,
so it's easy to provide a mocked-up 
  +              implementation of the interface.</li>
  +            <li>Services collaborate via <link href="ioc.html">dependency injection</link>,
so it's easy for a unit 
  +              test to wire a service to real or mock implementations of collaborating services.</li>
  +            <li>Because configuration data is just lists of Java objects, unit tests
can easily create objects suitable 
  +              for testing.</li>
  +          </ul>
  +        </section>
  +      </section>
  +    </section>
   	</body>
   </document>
  
  
  
  1.8       +1 -1      jakarta-hivemind/src/documentation/content/xdocs/configurations.xml
  
  Index: configurations.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-hivemind/src/documentation/content/xdocs/configurations.xml,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- configurations.xml	6 Aug 2004 14:16:41 -0000	1.7
  +++ configurations.xml	17 Aug 2004 12:33:22 -0000	1.8
  @@ -250,7 +250,7 @@
   						inside HiveMind, which uses the schema and rules to validate and
   						convert the XML contributions into Java objects.</p>
   					<p>You can omit the schema, in which case the elements are left as XML
  -						(instances of &api.Element; and your code is responsible for walking
  +						(instances of &api.Element;) and your code is responsible for walking
   						the elements and attributes ... but why bother? Far easier to let
   						HiveMind do the conversions and validations.</p>
   				</li>
  
  
  
  1.5       +5 -1      jakarta-hivemind/src/documentation/content/xdocs/dependencies.xml
  
  Index: dependencies.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-hivemind/src/documentation/content/xdocs/dependencies.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- dependencies.xml	6 Aug 2004 14:16:41 -0000	1.4
  +++ dependencies.xml	17 Aug 2004 12:33:22 -0000	1.5
  @@ -50,7 +50,7 @@
         <td>
           <link href="http://www.easymock.org/">EasyMock testing framework</link>
         </td>
  -      <td>Only needed by &api.HiveMindTestCase;, which exists as the basis of
your own tests.</td>
  +      <td>Only needed by &api.HiveMindTestCase;, which exists as the basis for
your own tests.</td>
       </tr>
       <tr>
         <td>jboss-j2ee-3.2.1.jar</td>
  @@ -84,6 +84,10 @@
           service.</td>
       </tr>
     </table>
  +  
  +  <p> Typically, all you need is the HiveMind libraries, Javassist, ORO and commons-logging.
Your EJB container will 
  +    provide the <code>javax.ejb</code> classes. Obviously, you should include
Spring if your are using Spring, and 
  +    EasyMock if you are writing tests using the <code>HiveMindTestCase</code>
base class. </p>
     
     <p>
       In most cases, HiveMind has been built against a "handy" version; in all likelyhood
you can vary
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: hivemind-cvs-unsubscribe@jakarta.apache.org
For additional commands, e-mail: hivemind-cvs-help@jakarta.apache.org


Mime
View raw message