JicarillaHTTP

The jicarilla container provides a compact inversion-of-control container API. It is so compact, in fact, that it can do so without requiring any interface representation!

Overview

Typical usage involves registering some classes and some component definitions with a container builder, retrieving a resolver from that builder, and then retrieving instances of the registered classes from that resolver. Behind the scenes, the container does its magic:

• it handles the instantiation, initialization and disposal of the instances;
• it provides the instances with their external dependencies and their configuration;
• it can transparently support different "lifestyles", like "singleton" instances, single-use instances, per-thread instances, per-request instances, pooled instances, and others;
• it can handle the lookup of instances from some kind of server or directory, using protocols like JNDI, JMX, SOAP, RMI or AltRMI. It can even use these instances in satisfying the dependencies of other instances;
• it can handle the exporting of hosted instances to a similar server or directory, providing transparent interoperability with many diverse environments;
• it can handle the activation and passivation (persistence) of instances, using mechanisms such as Hibernate, Prevayler, XStream or JDO;
• do many other things depending on what extensions you plug in (do instrumentation and profiling, method tracing, custom interception, load balancing, etc etc.);

Most importantly, though each and every one of these features, and all the other features not mentioned yet, are fully pluggable. This means that you can start with a really small and simple container that does none of these things, and gradually add extensions to make it do exactly what you want. No more and no less. And because of this highly modular architecture, it is quite easy to create and add your own extensions.

Of course, many users have no desire to do all this feature selection themselves and just want a package that does what they need "with a few clicks". To support this desire, jicarilla-container is packaged up together with preconfigured settings into several different profiles. Just like java itself has different distributions (mobile, core, enterprise), we package up the jicarilla container in several different ways as well:

• micro. Just the basics in a jar. If you want to do everything yourself.
• gui. The basics, plus all the materials you need for productive GUI client applications.
• power. The basics, plus lots of extensions that integrate the jicarilla container seamlessly with other container solutions and with many remote registries.
• web. The power profile, with additional extensions that integrate the jicarilla container inside the prevalent web technologies (servlets, struts, webwork, hibernate, ...)
• enterprise. The web profile with additional extensions that integrate the jicarilla container inside the prevalent enterprise technologies (JMX, JNDI, EJB, ..._
• kitchensink. All of the above, plus a huge preloaded library of components, applications and examples.

Inversion of Control Basics

You may associate Inversion of Control (or IoC for short) with big and complex server application frameworks like Avalon, or solutions for developing J2EE-based web applications like Spring Framework. Fortunately, the basics of IoC are far simpler than any of those:

    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 );

    public HomerAndApuScript first = new HomerAndApuScript(
            (HotdogBuyer)homer, apu );
    public AllInTheFamilyScript second = new AllInTheFamilyScript(
            homer, marge, bart, lisa, maggie );

    public Script dbl = new DoubleEpisodeScript( first, second );
    dbl.runEpisode();

The important idea is that we have a container (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).

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 Jicarilla website.

Getting Started with the Builder and Resolver


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...
here's a jicarilla-container-based version of the
"manual" Simpson container above:

    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 );
    script.runEpisode();


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.

Core Interfaces


{@link org.jicarilla.container.builder.Builder}
The Builder 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
Container 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 Resolver:

{@link org.jicarilla.container.Resolver}
The Resolver 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 Container.
This may lead you to compare the Resolver with a naming or
directory service like
JNDI. 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 your components
are never aware of the existence of the Resolver. In fact,
your components are never aware that they are living a Container
at all!


{@link org.jicarilla.container.Container},
{@link org.jicarilla.container.KeyRelayingContainer},
The Container 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 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
Container either.

{@link org.jicarilla.container.Adapter},
{@link org.jicarilla.container.KeyAwareAdapter}
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 Adapters instead. In operating
system terms, that means we would call the Container a
microkernel. While in the majority of cases, you have little reason to use an
Adapter directly, if you're doing really advanced stuff (like
linking components living within your own variant of CORBA into the
jicarilla-container system), Adapters are what you would need to
write to make it happen.

{@link org.jicarilla.container.Factory}
You're probably familiar with the concept of Factories. 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 Factories 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.

Type-1, Type-2, Type-3, Type-4, Type-e^2 IoC Support


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.

In other words, this means that you'll be able to easily plug in components
written for


avalon
picocontainer
spring framework
webwork
keel
cocoon



With little effort and without having to rewrite (or even recompile) your
components. Neath, huh?

todo: specific documentation on doing this kind of thing.

Non-IoC Component Support


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.

todo: specific documentation on doing this kind of thing, rather than
just bragging about it.

An implementation of HTTP/1.1, both client and server elements.

The main package provides the basic material needed for working with HTTP; the server subpackage provides an actual webserver; the util package contains some miscellaneous reusable classes helpful in implementing the HTTP spec.

The jicarilla framework provides a compact COP/IoC/SoC/event-based API. It is so compact, in fact, that COP nor IoC nor SoC require any kind of interface representation!

Typical usage is basically defining a few services and hooking them up using a few sinks, sources, and/or pipelines to each other and the world, then throwing everything into a container which will hold your components for you.

Besides provision for these patterns, the jicarilla framework also provides some common low-level utilities and interfaces, like support for Assertions, cascading exceptions, and more.

Terminology

Please refer to http://wiki.codehaus.org/picocontainer/PicoTerminology for definitions of basic terms used.

Event pipeline plumbing basics

A lot of information and tips about the use of the jicarilla framework interfaces is kept with the interfaces themselves. Here's a brief overview of the basis:

Event, message
The object which travels through the event-based system. With the jicarilla framework, it really can be any object. In an application, this will usually be a more specific type of event, though that's not a requirement.

pipeline, plumbing
We draw an analogy between event-based programming and the work of a plumber. Just like the plumber connects pipes, sinks, drains, valves, sources and the like to control the flow of water through a plumbing system, we connect their virtual counterparts to control the flow of messages through our event system.

{@link org.jicarilla.lang.plumbing.Source source}
Continuing our analogy, a source in the physical world could be a spring, a well, a tap, a reservoir, etc. Virtual equivalents can be sockets, event listeners, state monitors, timers, and others. Sources are the starting point of our plumbing.

{@link org.jicarilla.lang.plumbing.Sink sink}
Likewise, the drains, sinks and holes in the physical world have counterparts in our event model. Possible sinks include sockets, event handlers, resource recyclers, and others.

{@link org.jicarilla.lang.plumbing.Stage stages, channels}
Anything that is a source on one end and a sink on the other end is a stage. In the real world, stages can be thought of as the pipes interconnecting sources and sinks. In our model, everything that supports both the source and the sink interface can be effectively used as a stage.

other components
In handling the water management in your house, a plumber doesn't just use taps, drains, and channels. Different ways of interconnecting those basic parts are required as well, like a T-section, various valves, slow-downs and speed-ups, pumps, and much more. The event model is no different. Among the basic interconnection components are:
• {@link org.jicarilla.lang.Alternator Alternators}, for distributing messages (roughly) evenly across multiple sinks;
• {@link org.jicarilla.lang.plumbing.Collector Collectors}, for combining messages from several sources into a single new source;
• {@link org.jicarilla.lang.plumbing.Multicaster Multicasters}, for broadcasting a message to multiple sinks; and
• {@link org.jicarilla.lang.AsyncEnabled AsyncEnabled}, for distributing messages to one of multiple sinks based on some policy.

Besides these, classes of note that have to do with the event basics include:

• {@link org.jicarilla.lang.AsyncEnabled AsyncEnabled}, for crossing the gap between basic method-call-based messaging and jicarilla-plumbing-style messaging;
• {@link org.jicarilla.lang.Selector Selector}, a very generic helper class used by {@link org.jicarilla.lang.plumbing.Screener Screeners}.

The implementation jar for jicarilla framework (or the combined interface+implementation jar if you prefer it) contains basic implementations of all of these interfaces, as well as several abstract base classes that make creating custom interfaces easier.

These event mechanisms are loosely based on the lightweight executable framework(s) described in Doug Lea's excellent book, Concurrent Programming in Java. Doug Lea's util.concurrent package is used in their implementation.

Utility classes

Many classes and interfaces don't really "fit" in a particular package or framework, yet they are so commonly needed as to warrant inclusion in one of the jars / core dependencies for any project. The jicarilla framework includes a few of these. The criterion for inclusion of a class of interface is simple: if its vital for use inside the jicarila framework itself or inside the jicarilla container, inclusion is considered based on an evaluation of the general applicability of the class or interface.

Current utility classes and interfaces include:

{@link org.jicarilla.lang.CascadingError}, {@link org.jicarilla.lang.CascadingException}, {@link org.jicarilla.lang.CascadingThrowable}

Prior to JDK 1.3, stack traces were inconsistently kept for various exceptions. In order to create full stack traces, it was neccessary to reference the offending exception whenever creating a new one. These classes provided support for rich stack traces in a pre-jdk-1.3 environment by allowing you to specify a the exception that "caused" the new exception, creating a cascade. They are backwards compatible from jdk 1.0 and forwards compatible up to at least jdk-1.4, but likely all the way up to all feature versions of java.

All exceptions within jicarilla inherit from one of these base classes, and there's nothing from stopping you doing the same in all your applications. Alternatively, you may want to look at one of the several equivalents of these classes that exist in:

• Avalon-Framework
• commons-lang

{@link org.jicarilla.lang.Active}
Despite all efforts to create COP frameworks without any sort of lifecycle beyond a simple constructor, and every now and then a finalize(), we still need initialize() and dispose() methods if we work in a multi-threaded environment (it's usually illegal to create threads in a constructor). The Active interface merges the two.

Note that functional equivalents exist in:
• Avalon-Framework
• PicoContainer
• JContainer DNA

{@link org.jicarilla.lang.Assert}
Starting with JDK 1.4, java has assertions through the assert keyword. However, that's a backwards-incompatible keyword, hence it is not available in a lot of environments. Fortunaly, the functionality offered by assert is easily emulated. The JUnit testing framework has included an Assert class for ages, and its proven to be tremendously useful. The jicarilla framework has one, too, and it is used extensively throughout the jicarilla platform.

{@link org.jicarilla.lang.ExceptionListener}
Most java applications I know have extensive amounts of logging statements throughout their code, usually done by using a library like
• log4j
• commons-logging
• avalon-framework logging

That's a shame, because not only are the tons of logging statements quite ugly, a lot of information is inevitably lost when an exception (which is what is usually logged) is converted to a string. It just limits the possibilities.

With the trivially simple ExceptionListener interface and the supporting implementation code, the decision whether to log anything or not, at what "log level", or any other actions to take is deferred to somewhere else. This leads to cleaner, more flexible, and simpler code. (Which is a rare combination!)

{@link org.jicarilla.lang.ReadonlyEnabled ReadonlyEnabled}
If possible We'd always have conceptually immutable components actually be immutable from the moment they return from their constructor. That's not always feasible. When its not, the ReadonlyEnabled interface can be used as a common way to mark components immutable at a later point in their lifetime.

{@link org.jicarilla.lang.Recyclable Recyclable}
Despite all the improvements in JVM technology, the new keyword is often still one of the main resource costs in java programming. It is often much cheaper to set a reference to null than it is to destroy an existing instance, then create a new one. If this is the case, and the performance matters, we can recycle our objects. The Recyclable interface specifies a simple recycle() method that tells an object to do just that to itself. Use it wherever instantiation/destruction becomes an unnacceptable bottleneck in your system.

Combining utility interfaces

What happens if you combine the Active, AsyncEnabled and Recyclable interfaces? Naturally, they can work together perfectly fine. Let's look at two common combinations that deserve some particular attention.

Active with Recyclable

The Active interface defines part of the component lifecycle, together with rather formal and exacting definitions of component state. The Recyclable interface does no such thing: it assumes that its implementation is a simple well-behaved component that is always in a consistent state. We should give some thought to what happens when we mix the two. At your discretion, you can modify the contract for Active to allow {@link org.jicarilla.lang.Recyclable#recycle()} to be called after dispose(). This would effectively allow for some "restartable" components. Something like the follow would be valid:

                                                                    // FRAGMENT
  ActiveAndRecyclableComponent aar = new ActiveAndRecyclableComponent();
  aar.initialize();

  aar.doStuff();
  aar.doMoreStuff();

  aar.dispose();
  aar.recycle();

  aar.doStuff();
  aar.doStuff();
  aar.doStuff();
  aar.doStuff();
  aar.doStuff();

  aar.dispose();
  aar.initialize();
  aar.dispose();
  aar.recycle();
  aar.initialize();
  aar.dispose();

This is a very dumb example, of course. In some very specific cases, this can be useful functionality, and the option is there (in fact, its sort-of implemented by {@link org.jicarilla.lang.AbstractActive#lazyInitialization()}. But I recommend you try alternative solutions first, since this is the first step to an overly complex and confusing component lifecycle.

Active with AsyncEnabled

This is a common combination, and a good one. Asynchronous components often use a worked threads (or multiple workers, or a worker thread pool, or a lightweight executable framework) to implement their asynchronous messaging. It is a good idea to create these active materials as part of an initialize()/dispose() sequence (remember: don't create threads inside constructors!).

Some notes about thread safety

All the event-related interfaces and classes in jicarilla framework are safe for concurrent usage. Why? Because event-based programming usually only makes sense in a multi-threaded environment, hence we almost always need thread safety. The interfaces and classes that are not directly event-related are not synchronized, but for each of them, its highly unlikely you will ever run into problems because of that.

Some notes about duplication

Several classes for which functional equivalents exist in other locations have been duplicated inside the jicarilla framework. Why? Because it can be highly annoying to introduce an external dependency on a jar not under your control just because you want to use 2% of its functionality. As far as I know, full credit is given to the original authors/projects in any and all files, as well as to projects/authors that were a source of insipiration, and all licensing requirements are satisfied. I hope everyone can see the rationale behind the duplication and not be offended by it.

An implementation of a generic, multithreaded, non-blocking, event-based Socket server.

This package defines the connection between the net and the http package, defining various building blocks for creating a request/response processing pipeline.

Note that, in general, pipeline stages are not multithreaded. Request/response pairs should be sent through a pipeline sequentially.