Update of /cvsroot/jicarilla/jicarilla-sandbox/platform/container/api/src/java/org/jicarilla/container
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv18414/platform/container/api/src/java/org/jicarilla/container
Modified Files:
package.html
Log Message:
docs, docs, docs
Index: package.html
===================================================================
RCS file: /cvsroot/jicarilla/jicarilla-sandbox/platform/container/api/src/java/org/jicarilla/container/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- package.html 8 Jan 2004 16:51:39 -0000 1.1
+++ package.html 29 Feb 2004 20:29:13 -0000 1.2
@@ -3,13 +3,6 @@
API. It is so compact, in fact, that it can do so without requiring any
interface representation!</p>
-<p><b>warning! warning! warning!</b></p>
-<p>The jicarilla-container package is brand-new, and aside from some of the
-core interfaces, it is in very active development. Documentation will not
-coincide with the current future set, the api is in a state of constant flux,
-etc. Please look around if you're interested, but don't expect something to
-work tomorrow just because it does today.</p>
-
<h3>Overview</h3>
<a name="Overview"></a>
@@ -81,99 +74,183 @@
Fortunately, the basics of IoC are far simpler than any of those:</p>
<pre>
- public ManualSimpsonContainer()
- {
- // todo: fix
- Apu apu = new ApuImpl();
- Marge marge = new MargeImpl();
- Homer homer = new HomerImpl( marge );
- Bart bart = new BartImpl( homer, marge );
- Lisa lisa = new LisaImpl( homer, marge );
- Maggie maggie = new MaggieImpl();
- ((MaggieImpl)maggie).setHomer( homer );
- ((MaggieImpl)maggie).setMarge( marge );
-
- Script first = new HomerAndApuScript( (HotdogBuyer)homer, apu );
- Script second = new AllInTheFamilyScript(
- homer, marge, bart, lisa, maggie );
+ public Apu apu = new ApuImpl();
+ public Marge marge = new MargeImpl();
+ public Homer homer = new HomerImpl( marge );
+ public Bart bart = new BartImpl( homer, marge );
+ public Lisa lisa = new LisaImpl( homer, marge );
+ public Maggie maggie = new MaggieImpl( homer, marge );
- Script dbl = new DoubleEpisodeScript( first, second );
+ public HomerAndApuScript first = new HomerAndApuScript(
+ (HotdogBuyer)homer, apu );
+ public AllInTheFamilyScript second = new AllInTheFamilyScript(
+ homer, marge, bart, lisa, maggie );
- setScript( dbl );
- }
+ public Script dbl = new DoubleEpisodeScript( first, second );
+ dbl.runEpisode();
<pre>
+<p>The important idea is that we have a <strong>container</strong> (in this
+case just a short code snippet) that is responsible for creating components,
+glueing them together, and telling them what to do. Control over the
+application flow starts at the top (with the container) and flows down (to
+the components).</p>
+
+<p>A lot of people have written a lot more about inversion of control (or
+the "hollywood principle" as it has also been called), and you can find links
+to various papers on the <a href="http://jicarilla.org/">Jicarilla website</a>.
+
<h3>Getting Started with the Builder and Resolver</h3>
<a name="GettingStartedWithTheBuilderAndResolver"></a>
<p>The easiest way to get a feel for how to work with the jicarilla
-container is to look at an example. Continuing the simpsons example...
+container is to look at an example. Continuing the Simpsons example...
here's a jicarilla-container-based version of the
-ManualSimpsonContainer:</p>
+"manual" Simpson container above:</p>
<pre>
- public JicarillaSimpsonContainer()
- {
- // todo: fix!
- Resolver resolver =
- DefaultBuilder.newInstance()
- .addComponent( HomerImpl.class )
- .addComponent( YoungHomer.class )
-
- .addComponent( new HomerImpl() )
- .addComponent( new BartImpl() )
- .addComponent(
- new ClassSelector( Marge.class ),
- new SingletonComponentAdapter(
- new ManualComponentFactory(
- new MargeImpl()
- )
- )
- )
+ Resolver resolver =
+ DefaultBuilder.newInstance()
+ .addComponent( "homer-and-apu", HomerAndApuScript.class )
+ .addComponent( "all-in-the-family",
+ AllInTheFamilyScript.class )
+ .addComponent( ApuImpl.class )
+ .addComponent( BartImpl.class )
+ .addComponent( HomerImpl.class )
.addComponent( LisaImpl.class )
+ .addComponent( MaggieImpl.class )
+ .addComponent( MargeImpl.class )
+ .addComponent(
+ new CustomComponentFactory // todo: create this class
+ (
+ DoubleEpisodeScript.class,
+ new Object[]
+ {
+ "homer-and-apu",
+ "all-in-the-family"
+ }
+ )
+ )
.create();
- Script script = (Script)resolver.get(Script.class);
- setScript( script );
- }
+ Script script = (Script)resolver.get( Script.class );
+ script.runEpisode();
</pre>
+<p>From this simple example, it may not be immediately apparent what benefit
+you get from using jicarilla. After all, the functionality is the same, and
+the second one is easier to read and understand. But take another look at the
+second example. Note how the episode scripts are added before we add any of
+the Simpsons characters themselves. You don't have to worry about correctly
+ordering all your object creations. This is but a small taste of the huge
+benefits you can get from using the jicarilla-container package.</p>
+
<h3>Core Interfaces</h3>
<a name="CoreInterfaces"></a>
-<p>todo</p>
-
-<h3>Type-1, Type-2, and Type-3 IoC Support</h3>
-<a name="Type1Type2Type3AndType3IoCSupport"></a>
+<ul><b>{@link org.jicarilla.container.builder.Builder}</b>
+<ul>The <code>Builder</code> is half of your main interface to the
+jicarilla-container package. It hides much of the complexity and magic that
+goes on "behind the screen" in the internals of the container package. You use
+it just like we did in the example above, to create and populate a
+<code>Container</code> instance with all your components. When you are finished
+populating the container, you call
+{@link org.jicarilla.container.builder.Builder#create()} to get access to an
+instance of a <code>Resolver</code>:</ul></ul>
-<p>todo</p>
+<ul><b>{@link org.jicarilla.container.Resolver}</b>
+<ul>The <code>Resolver</code> is that other half of your main interface to the
+jicarilla-container package. You use it just like we did in the example above,
+to retrieve references to components that live inside a <code>Container</code>.
+This may lead you to compare the <code>Resolver</code> with a naming or
+directory service like
+<code><a href="http://java.sun.com/products/jndi/">JNDI</a>. While you could
+use a resolver much like you use JNDI, this is not usually a good idea. Instead
+of all your components looking up things inside the JNDI directory, the
+container is responsible for doing that for them. So <i>your components
+are never aware of the existence of the <code>Resolver</code></i>. In fact,
+your components are never aware that they are living a <code>Container</code>
+at all!</ul></ul>
-<h3>Integration With Third-Party IoC Solutions</h3>
-<a name="IntegrationWithThirdPartyIoCSolutions"></a>
+<ul><b>{@link org.jicarilla.container.Container},
+{@link org.jicarilla.container.KeyRelayingContainer},</b>
+<ul>The <code>Container</code> is the "meat" of the jicarilla-container
+package. It is the "fundamental abstraction", the spider in the center of the
+web. If jicarilla-container where an operating system, the
+Ccode>Container</code> is what we would call the kernel. And just like 99% of
+the time, you have no particular interest in interacting directly with the
+operating system kernel, you usually don't interact directly with the
+<code>Container</code> either.</ul></ul>
-<p>todo</p>
+<ul><b>{@link org.jicarilla.container.Adapter},
+{@link org.jicarilla.container.KeyAwareAdapter}</b>
+<ul>These two interfaces are the "smart trick" that makes jicarilla-container
+so agile, flexible and extensible. A lot of responsibility is taken away from
+the container and lives inside <code>Adapters</code> instead. In operating
+system terms, that means we would call the <code>Container</code> a
+microkernel. While in the majority of cases, you have little reason to use an
+<code>Adapter</code> directly, if you're doing really advanced stuff (like
+linking components living within your own variant of CORBA into the
+jicarilla-container system), <code>Adapter</code>s are what you would need to
+write to make it happen.</ul></ul>
-<h4>PicoContainer Integration</h4>
-<a name="PicoContainerIntegration"></a>
+<ul><b>{@link org.jicarilla.container.Factory}</b>
+<ul>You're probably familiar with the concept of <code>Factories</code>. They
+are "helper objects", often associated with a particular class, that are
+responsible for creating new instances of that class. They're commonly used
+when simply putting all the creation and instantiation directly inside the
+class constructor results in a really big and ugly constructor. The use of
+factories inside the jicarilla-container package is no different. The main
+thing that sets the jicarilla <code>Factories</code> apart from other factories
+is that they are quite "general". By using some pretty smart reflection and
+introspection magic, a handful of factories can be used for the instantiation
+of dozens (or thousands in a complex system, or even millions if you want to
+get silly) of different classes.</ul></ul>
-<p>todo</p>
+<h3>Type-1, Type-2, Type-3, Type-4, Type-e^2 IoC Support</h3>
+<a name="Type1Type2Type3AndType3IoCSupport"></a>
-<h4>XWork Integration</h4>
-<a name="XWorkIntegration"></a>
+<p>You may have heard the buzz surrounding Inversion of Control, and the new
+buzzword introduced recently, "dependency injection". You may also have been
+quite ignorant of it all. Either case, jicarilla-container provides built-in,
+no-brainer, complete, simple, and integrated support for all the flavors of
+IoC that are currently popular. And its real easy to add support for new
+flavors as well.</p>
-<p>todo</p>
+<p>In other words, this means that you'll be able to easily plug in components
+written for</p>
-<h4>Spring Framwork Integration</h4>
-<a name="SpringFrameworkIntegration"></a>
+<ul>
+<li><a href="http://avalon.apache.org/">avalon</a></li>
+<li><a href="http://www.picocontainer.org/">picocontainer</a></li>
+<li><a href="http://www.springframework.org/">spring framework</a></li>
+<li><a href="http://www.opensymphony.com/webwork/">webwork</a></li>
+<li><a href="http://www.keelframework.org/">keel</a></li>
+<li><a href="http://cocoon.apache.org/">cocoon</a></li>
+<!-- TODO: <li><a href="http://www.jcontainer.org/loom/">loom</a></li>
+<li><a href="http://www.jcontainer.org/dna/">dna</a></li>
+<li><a href="http://plexus.codehaus.org/">plexus</a></li>
+<li><a href="http://www.enterpriseobjectbroker.org/">EOB</a></li>
+-->
+</ul>
-<p>todo</p>
+<p>With little effort and without having to rewrite (or even recompile) your
+components. Neath, huh?</p>
-<h4>Avalon Integration</h4>
-<a name="AvalonIntegration"></a>
+<p>todo: specific documentation on doing this kind of thing.</p>
-<p>todo</p>
+<h3>Non-IoC Component Support</h3>
+<a name="NonIoCComponentSupport"></a>
+<p>But it doesn't stop there! With (usually) just a teeny weeny little bit
+more effort, you can plug in EJBs, servlets, Plain Old Java Objects (POJOs),
+JDBC data sources, xml files (!), property files, JNDI-hosted components,
+JMX-exported components, OSGi bundles, eclipse plugins, SOAP services,
+CORBA objects, RMI-exported services, and 20-year-old punchcards! Okay, I may
+be getting just a little carried away here, but you get the general idea,
+I hope.</p>
-<p>etc etc etc</p>
+<p>todo: specific documentation on doing this kind of thing, rather than
+just bragging about it.</p>
</body>
-------------------------------------------------------
SF.Net is sponsored by: Speed Start Your Linux Apps Now.
Build and deploy apps & Web services for Linux with
a free DVD software kit from IBM. Click Now!
http://ads.osdn.com/?ad_id=1356&alloc_id=3438&op=click
lmpx.com only provides a reader for public news (NNTP) servers. It is not
affiliated with the servers or forums shown here and is not responsible for
the content of articles, which is written by their respective authors.