hivemind-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r506137 - /hivemind/hivemind2/trunk/src/site/xdoc/index.xml
Date Sun, 11 Feb 2007 21:08:09 GMT
Author: ahuegen
Date: Sun Feb 11 13:08:09 2007
New Revision: 506137

Added alpha version hints


Modified: hivemind/hivemind2/trunk/src/site/xdoc/index.xml
--- hivemind/hivemind2/trunk/src/site/xdoc/index.xml (original)
+++ hivemind/hivemind2/trunk/src/site/xdoc/index.xml Sun Feb 11 13:08:09 2007
@@ -16,305 +16,30 @@
-	<header>
+	<properties>
 		<title>Introduction to HiveMind</title>
-	</header>
+	</properties>
-		<p><strong>HiveMind</strong> is a services and configuration microkernel:</p>
-		<ul>
-			<li><strong><link href="site:services">Services</link></strong>:
-				services are <em>POJOs</em> (Plain Old Java Objects) that can be easily
-				accessed and combined. Each service ideally defines a Java interface it
-				implements (but this is no longer mandatory). HiveMind takes care of instantiating and
configuring each
-				service just as necessary. HiveMind lets services collaborate with each
-				other via <link href="site:ioc">dependency injection</link>.</li>
-			<li> <strong><link href="site:configurations">Configuration</link></strong>:

-				HiveMind allows you to provide complex configuration data to your
-				services in a format <em>you</em> define. HiveMind will integrate the
-				contributions of such data from multiple modules and convert it all into
-				data objects for you. HiveMind configurations allow for powerful,
-				data-driven solutions which combine seemlessly with the service
-				architecture.</li>
-			<li><strong>Microkernel</strong>: HiveMind is a framework for creating
applications, not
-				an application, or even an application server, itself. The 'core' of HiveMind
-				is the <link href="site:bootstrap">startup logic</link>
-			  that knows how to parse and understand the
-				<link href="site:descriptor">module deployment descriptors</link>, and use
-				information to <link href="site:ioc">instantiate and initialize</link>
-				all those services and configurations.
-				</li>
-		</ul>
-		<p>In HiveMind, a service is an implementation of a Java interface. Unlike
-			other SOAs (Service Oriented Architectures, such as a SOAP, or EJBs),
-			HiveMind is explicitly about combining Java code within a single JVM.
-			HiveMind uses a <link href="site:descriptor">descriptor</link> to describe
-			different services, their lifecycles, and how they are combined. HiveMind
-			takes care of thread-safe, just-in-time creation of singleton service
-			objects so your code doesn't have to.</p>
-    <p>
-      HiveMind sits between your application code and the underlying J2EE or other APIs:
-    </p>
-    <figure src="images/FrameworkStack.png" alt="[Framework Stack]"/>
-    <p>
-     In this diagram, the application accesses key HiveMind services (the small circles).
These services
-     acts as facades; the implementations of 
-     the services are dependent on many other services, as well as configurations (the blue
stacks of blocks).
-     Service implementations make use of Java and J2EE APIs, and may even "bridge" into other
systems such
-     as EJB session beans.     
-    </p>
-		<p>HiveMind is organized around <em>modules</em>: individual building
-			blocks, each providing a particular set of services and configurations.
-			Each module is deployed as its own JAR file, containing its own <link
-			href="site:descriptor">descriptor</link>. At runtime, HiveMind combines 
-			<em>all</em> the modules and their descriptors together ... seemlessly
-			combining the services specific to your application with the services
-			provided by HiveMind and by other third-party libraries.</p>
-		<p>HiveMind is designed with particular attention to J2EE. Because J2EE
-			applications are multi-threaded, everything in HiveMind is thread-safe.
-			That's one less thing for you to be concerned about.</p>
-		<p>HiveMind allows you to create more complex applications, yet keep the
-			individual pieces (the individual services) simple and testable. HiveMind enourages the
-      of common best practices, such as coding to interfaces, seperation of concerns, and
-      code highly testable without a special container. </p>
-		<section>
-			<title>Status</title>
-			<p>HiveMind 2.0.0 is released as alpha version</p>
-		  <warning>
-		    This documentation covers HiveMind 2.0, currently in an early alpha stage of development.
-		  </warning>
-		</section>
-    <section>
-      <title>Upgrade warnings (release 1.x to release 2.0)</title>
-      <p>For the most part, code that works with HiveMind 1.x will work with HiveMind
2.0 as well.  
-        There have been a small number
-        of incompatible changes between releases that will not affect the vast majority of
-        <ul>
-          <li>The</li>
-        </ul>
-    </section>
-		<section>
-			<title>Coding</title>
-			<p>Coding using HiveMind is designed to be as succinct and painless as
-				possible. Since services are, ultimately, simple objects (POJOs -- plain
-				old java objects) within the same JVM, all the complexity of J2EE falls
-				away ... no more JNDI lookups, no more RemoteExceptions, no more home
-				and remote interfaces. Of course, you can still use HiveMind to 
-				<link href="site:hivemind.lib.EJBProxyFactory">front your 
-				EJBs</link>, in which case the service is
-				responsible for performing the JNDI lookup and so forth (which in itself
-				has a lot of value), before forwarding the request to the EJB.</p>
-			<p>In any case, the code should be short. To external objects (objects
-				that are not managed by HiveMind, such as a servlet) the code for
-				accessing a service is quite streamlined:</p>
-			<javasource><![CDATA[
-Registry registry = RegistryBuilder.constructDefaultRegistry();
-MyService service = (MyService) registry.getService("com.mypackage.MyService", MyService.class);
-    ]]></javasource>
-			<p>You code is responsible for:</p>
-			<ul>
-				<li>Obtaining a reference to the Registry singleton</li>
-				<li>Knowing the complete id of the service to access</li>
-				<li>Passing in the interface class</li>
-			</ul>
-			<p>HiveMind is responsible for:</p>
-			<ul>
-				<li>Finding the service, creating it as needed</li>
-				<li>Checking the type of the service against your code's expections</li>
-				<li>Operating in a completely thread-safe manner</li>
-				<li>Reporting any errors in a useful, verbose fashion</li>
-			</ul>
-      <note>
-        In the not-unusual case that only a single service within the entire Registry
-        implements a particular service interface, 
-        then you may omit the service id, i.e. <code>getService(MyService.class)</code>.
-      </note>
-			<p>However, a much more common case is for services to collaborate: that's
-				much simpler, since HiveMind will connect the two services together for
-				you. You'll just need to provide an instance variable and either a
-				setter method or a constructor argument.</p>
-		</section>
-		<section>
-			<title>Documentation</title>
-			<p>An important part of the HiveMind picture is documentation.
-				Comprehensive documentation about a HiveMind application, <link
-				href="site:hivedoc">HiveDoc</link>, can be automatically generated by
-				your build process. This documentation lists all modules, all extension
-				points (both service and configuration), all contributions (of service
-				constructors, service interceptors and configuration elements) and cross
-				links all extension points to their contributions.</p>
-			<p>Modules and extension points include a description which is
-				incorporated into the generated documentation.</p>
-			<p>HiveMind is used to construct very complex systems using a large number
-				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 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>
-          <javasource> <![CDATA[ 
-public String myMethod(String param)
-  if (LOG.isDebugEnabled()) 
-    LOG.debug("myMethod(" + param + ")");
-  String result = // . . . 
-  if (LOG.isDebugEnabled())
-    LOG.debug("myMethod() returns " + result); 
-  return result;
-}]]> </javasource>
-          <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 
-            <link href="../framework/descriptor.html#create-instance">&lt;create-instance&gt;</link>),
-            adds method logging (using <link href="../framework/descriptor.html#interceptor">&lt;interceptor&gt;</link>):</p>
-          <xmlsource><![CDATA[
-<service-point id="MyService" interface="com.myco.MyServiceInterface">
-  <create-instance class="com.myco.impl.MyServiceImpl"/>
-  <interceptor service-id="hivemind.LoggingInterceptor"/>
-</service-point>]]> </xmlsource>
-        </section>
-      </section>
-      <section>
-        <title>Task: Reference another service</title>
-        <section>
-          <title>Typical Approach</title>
-          <javasource><![CDATA[
-private SomeOtherService _otherService;
-public String myMethod(String param)
-  if (_otherService == null)
-    _otherService = // Lookup other service . . .
-  _otherService.doSomething(. . .);
-  . . .
-}]]> </javasource>
-          <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=""> dependency injection</link>.
HiveMind can 
-            inject dependencies using JavaBeans properties or constructor arguments.</p>
-          <javasource><![CDATA[
-private SomeOtherService _otherService;
-public void setOtherService(SomeOtherService otherService)
-  _otherService = otherService;
-public String myMethod(String param)
-  _otherService.doSomething(. . .);
-  . . .
-}]]> </javasource>
-          <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>
-          <javasource><![CDATA[
-private List _configuration;
-public void setConfiguration(List configuration)
-  _configuration = configuration;
-public void myMethod()
-  Iterator i = _configuration.iterator();
-  while (i.hasNext())
-  {
-    MyConfigItem item = (MyConfigItem);
-    item.doStuff(. . .);
-  }
-}]]> </javasource>
-          <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>
+	  <section name="Introduction to HiveMind 2" >
+	    <div>HiveMind 2 is a complete refactoring of HiveMind 1.
+	     The Refactoring was mainly done to support alternative ways of
+	     defining a registry and its services and configuration points.
+	     <br/>
+	     New features:
+	     <ul>
+	       <li>Pure Java Registry Definition API</li>
+	       <li>Annotation Based Definition API (Annotated modules)</li>
+	       <li>Extensible Autowiring Service</li>
+	       <li>Arbitrary Configuration Types</li>
+	     </ul>  
+	    </div>
+      <div style="border-color: red; border-style:solid; border-width: 1px; color:red;
padding:1em; padding-left: 2em; background-image: url(./images/icon_warning_sml.gif); background-repeat:
no-repeat; background-position: 5px 1em; ">
+				HiveMind 2 is currently in alpha stage. New documentation is 
+				created on the <a href="">wiki</a>.
+				Meanwhile you may have a look at the <a href="">HiveMind
1 documentation</a>.	
+				<br/>
+				Moreover be aware, that the new APIs are still subject to change.
+			</div>
+	  </section>

View raw message