avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From leosim...@apache.org
Subject cvs commit: jakarta-avalon/src/xdocs book.xml designing-a-component.xml getting-started.xml guide-cop-in-avalon.xml guide-cop-what-is.xml guide-oop-best-practices.xml guide-patterns-in-avalon.xml guide-patterns-ioc-security.xml guide-patterns-ioc.xml guide-patterns-soc.xml guide-patterns-soii.xml guide-patterns-what-are.xml guide-where-to-go-from-here.xml index.xml reference-containers.xml reference-the-lifecycle.xml tabs.xml
Date Wed, 05 Feb 2003 10:28:18 GMT
leosimons    2003/02/05 02:28:18

  Added:       src/xdocs book.xml designing-a-component.xml
                        getting-started.xml guide-cop-in-avalon.xml
                        guide-cop-what-is.xml guide-oop-best-practices.xml
                        guide-patterns-in-avalon.xml
                        guide-patterns-ioc-security.xml
                        guide-patterns-ioc.xml guide-patterns-soc.xml
                        guide-patterns-soii.xml guide-patterns-what-are.xml
                        guide-where-to-go-from-here.xml index.xml
                        reference-containers.xml
                        reference-the-lifecycle.xml tabs.xml
  Log:
  Putting in place the forrestized version of the framework docs from the proposal directory here
  
  Revision  Changes    Path
  1.17      +27 -44    jakarta-avalon/src/xdocs/book.xml
  
  
  
  
  1.1                  jakarta-avalon/src/xdocs/designing-a-component.xml
  
  Index: designing-a-component.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
  <document>
    <header>
      <title>Avalon Framework - Designing a Component</title>
      <version>1.0</version>
      <authors>
        <person name="Berin Loritsch" email="bloritsch@apache.org"/>
        <person name="Leo Simons" email="leosimons@apache.org"/>
      </authors>
    </header>
    <body>
        <section>
  <title>How is the Component Going to be Used?</title>
          <p>
            The first step in writing the component is determining how it is going
            to be used.  There will be a number of times where you have a powerful
            component that can be used in many different contexts.  Those contexts
            may include executing the component from the command line (separate
            from Avalon), using it as a part of a sub system, or using it as an
            integral part of Avalon.
          </p>
          <section>
  <title>Part of Avalon</title>
            <p>
              All components are an integral part of Avalon, so there is really
              nothing to be done beyond specifying its interface (role).  It is
              important to identify and document its social contract with the
              rest of the system.  What I mean by social contract is the order
              of dependencies, what it needs to function, and what it supplies
              to the rest of the system.
            </p>
          </section>
          <section>
  <title>Part of a Sub System</title>
            <p>
              A sub system can either be part of Avalon, or live in a separate
              context.  A perfect example would be a component that can function
              within a Servlet or Enterprise Application.  Neither of those
              contexts are native to Avalon (though they can easily be built
              on top of Avalon).
            </p>
            <p>
              It is important to do even more careful planning than in the
              first scenario.  The reason is that you want the interface to be
              as generic as possible and still accurately represent its role.
            </p>
            <p>
              Because the contexts may not be an integral part of Avalon,
              you must take care to use the component in the same manner as
              Avalon would.  That means that you follow the order of concerns
              that Avalon has specified for those concerns.
            </p>
          </section>
          <section>
  <title>A Stand Alone Program</title>
            <p>
              When you are designing a component to be run from the command
              line (or directly by the operating system), try to separate
              the main function from the component itself.  This is imperative
              in order to maintain the passive API of Avalon.  By designing
              your component in the manner stated in the previous section,
              you have effectively minimized what the main function has to
              do.
            </p>
            <p>
              Follow the practice of having an object dedicated to the main
              function that includes the parsing of the command line parameters
              and initialization of the component.  When the component is used
              the exact same way in every context (including the command line),
              you minimize the number of locations to look while debugging.
            </p>
            <note>
              A common mistake is to combine the main function in the
              implementation of the component.  This requires violating the
              contracts and principles that Avalon is built upon.  This
              violation of the pattern of "Inversion of Control" is
              aptly dubbed "Subversion of Control" (thanks to Steven Coffman
              for the name of the anti-pattern).
            </note>
          </section>
        </section>
    </body>
  </document>
  
  
  
  1.8       +36 -87    jakarta-avalon/src/xdocs/getting-started.xml
  
  
  
  
  1.1                  jakarta-avalon/src/xdocs/guide-cop-in-avalon.xml
  
  Index: guide-cop-in-avalon.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
  <document>
    <header>
      <title>Avalon Framework - Guide - COP in Avalon</title>
      <authors>
        <person name="Berin Loritsch" email="bloritsch@apache.org"/>
        <person name="Leo Simons" email="leosimons@apache.org"/>
      </authors>
    </header>
    <body>
      <section>
  <title>Components in Avalon</title>
        <p>
          At the core of the Avalon framework is the component. We define it as "a
          passive entity that performs a specific role". This is important to grasp
          because it requires a specific way of thinking.
        </p>
        <section>
  <title>A passive API</title>
          <p>
            A passive entity must employ a passive API. A passive API is one that is
            acted upon, versus one that acts itself. See the
            <link href="guide-patterns-ioc.html">Inversion of Control</link> pattern
            for an explanation.
          </p>
        </section>
        <section>
  <title>A specific Role</title>
          <p>
            The concept of roles comes from the theater.  A play, musical,
            or movie will have a certain number of roles that actors play.
            Although there never seems to be a shortage of actors, there
            are a finite number of roles.  I am not going to make reference
            to different types of roles at this point, but simply bring
            the concept to light.  The function or action of a role is
            defined by its script.
          </p>
          <p>
            We are introducing this concept now because you need to have it
            in mind when you are designing your system architecture.  Think
            of the different roles in your system, and you will have your
            "cast" of components so to speak.
          </p>
          <p>
            For each role, you need to specify its script, or interface to
            the rest of the system.  To be honest the interface is not enough.
            There are specific contracts that you must define and keep in mind
            when you specify your interfaces.  In other words, what users
            of the component must provide, and what the component produces.
            When the interfaces and contracts are defined, you can work on your
            implementation.
          </p>
        </section>
      </section>
  
  
      <section>
  <title>The Component</title>
        <p>
          John Donne wrote, "No man is an island." to communicate that we
          are all interdependent.  The same is true for the component.  That
          is why there are different concerns regarding the component.  In
          the section on roles we specified one of the concerns: the role.
          The concerns directly supported by the Avalon Framework are:
          configuration, external component use, management, and execution.
        </p>
        <note>
          We used to have a marker interface component. This has been deprecated
          because requiring all components extend this interface makes
          integrating Avalon with other component systems like
          <link href="http://www.corba.org">CORBA</link> very cumbersome.
        </note>
        <p>
          As you might have guessed, each one of these concerns has a separate
          interface that describes that concern.  We will delve deeper into
          the interfaces and the reasoning behind them in other sections.  It
          is important to know the order of precedence for the concerns so
          that you know the overall contracts of how they are put together.
        </p>
        <ol>
          <li>
            <strong>Configurable:</strong> marks an object that can be configured.
          </li>
          <li>
            <strong>Composable:</strong> marks an object that uses Components.
          </li>
          <li>
            <strong>Initializable:</strong> marks an object that can be initialized.
          </li>
          <li>
            <strong>Disposable:</strong> marks an object that can be disposed.
          </li>
          <li>
            <strong>Stoppable:</strong> marks an object that can be started and stopped.
          </li>
        </ol>
        <p>
          The contract surrounding this order means that the methods defined
          by each of those interfaces are called in a specific order by the object
          that created the component.  Each interface represents a narrow view
          of the component or object being controlled.
        </p>
        <note>
          Notice that each interface is separate from Component, so you can use
          them for simple objects.
        </note>
      </section>
  
      <section>
  <title>The Composable</title>
        <p>
          In Avalon, Composable is defined as an active entity that controls
          or uses components.  Its best analogy is that of a musical composer.
          The musical composer chooses instruments (components) by their
          role in the symphony (system) and tells them which notes to play.
        </p>
        <p>
          The Avalon Composable follows the principles of Inversion of Control,
          and is assigned a Component Manager.  Within this section we will
          discuss how to look up specific components, and then how to prepare
          the ComponentManager for the Composable.
        </p>
        <note>
          The Composable has a specific contract that must be enforced for security
          reasons.  The ComponentManager must only be set once.  That means that
          the <code>compose</code> method must ignore all subsequent
          requests to set the ComponentManager after it is successfully set.
        </note>
      </section>
  
      <section>
  <title>Finding your Component</title>
        <section>
  <title>The Component Manager</title>
          <p>
            For the majority of all cases, you will need to use the ComponentManager
            to get the instance of the component you need.  If you recall the discussion
            on component roles in the component documentation, you already have
            a head start.  In Avalon, roles are defined by the work interface a
            component has.  A work interface is different from any other interface
            because it is the interface that defines the component's role.  Composable
            and Component are concern interfaces because they address specific
            concerns about the component.
          </p>
          <p>
            The ComponentManager has one method to retrieve all of your components.
            The <code>lookup</code> method will look up the component based on the
            fully qualified name (FQN) of the work interface (Role).  It is important
            to realize that the ComponentManager returns Components, and therefore
            you must recast the Component to the role you need.  See the following
            example:
          </p>
          <source>
  final MyComponent component = (MyComponent)manager.
       lookup( "com.mycompany.myproject.MyComponent" );
          </source>
          <p>
            It is important to note that role is not the same thing as functional
            equivalence.  In other words, if you have a MailSpooler that is functionally
            equivalent to a FileStore (they do the same thing), it does not mean that
            they perform the same role.  The FileStore is used to store objects to
            files, and the MailSpooler is used to temporarily store messages until
            they are sent.  Thus they are separate roles.  Some containers require
            that the interface name match the key used to lookup component. In this
            situation you may need to create a new interface that does nothing
            more than extend another interface and add a new role.
          </p>
        </section>
        <section>
  <title>The Component Selector</title>
          <p>
            Sometimes you will have several components that function in the same role.
            For those cases, you will use the ComponentSelector to choose the exact
            one you need.  The best way to describe its proper use is the scenario
            described here.  You have several formatters that have the same role:
            to take an input document and format it according to the rules in the
            individual component implementations.  One formatter may take a text file
            and remove all tabs and replace them with four spaces.  Another formatter
            may reverse the formerly mentioned one.  Yet another takes the text file
            and formats it for a canvas object.  For the Composable, it makes no difference
            what the implementation does--just that it formats the text.
          </p>
          <p>
            Using the processing chain example in the previous paragraph, we realize
            the unsuitability of the ComponentManager for getting the right component.
            The component addresses the concern of one component per role.  Fortunately,
            the ComponentSelector is a component.  That means we use the ComponentManager
            to lookup the ComponentSelector.  The ComponentSelector is designed to choose
            the specific component out of many that perform the <strong>same</strong>
            role.  The following code will help:
          </p>
          <source>
  final ComponentSelector selector = (ComponentSelector)manager.
      lookup( "org.mycompany.myproject.FormatterSelector" );
  final Formatter formatter = (Formatter)selector.select( myURL );
          </source>
          <p>
            The selector does not discriminate against lookup keys.  In that respect it
            acts much like a hashtable lookup.  Keep in mind that the implementation of the
            selector does not limit you to a hashtable lookup--you can dynamically
            instantiate objects as well.  It takes an object (a hint), and returns the
            specific component based on that hint.
          </p>
  
  	<note>
  	Discussions are currently taking place about the ComponentSelector interface and
  	concept. It might be deprecated at some point in the future. There are indications
  	that usage of the ComponentSelector is only required when an application is
  	badly designed.
  	</note>
        </section>
        <section>
  <title>When you are done with the Component</title>
          <p>
  	  Both the ComponentManager and the ComponentSelector require you to
  	  release your component when you are done with it.  The method used
  	  to do this is "release".  One way of handling this is to use the
  	  try/catch/finally construct.  For your convenience, the following
  	  code can help:
  	</p>
  	<source>
  MyComponent component = null;
  
  try
  {
      component = (MyComponent) manager.lookup("org.mycom.MyComponent");
      component.myMethod();
  }
  catch (Exception e)
  {
      getLogger().debug("Error using MyComponent", e);
  }
  finally
  {
      if (component != null) manager.release(component);
  }
  	</source>
  	<p>
  	  The reason for this is so that smart component managers that
  	  select components from a pool can properly manage the resources.
  	</p>
        </section>
      </section>
  
      <section>
  <title>Populating the ComponentManager</title>
        <p>
          It is the responsibility of the entity that creates the Composable to give it a
          ComponentManager with all of the Roles populated.  If you create your own
          implementations of the ComponentManager and ComponentSelector then you have
          the liberty of deciding how to populate them.  Keep in mind that there are
          default implementations included, and you should model their behavior as
          much as possible.
        </p>
        <section>
  <title>DefaultComponentManager</title>
          <p>
            The DefaultComponentManager is nothing more than a Hashtable lookup of roles
            and Components.  It even gives you the method <code>put</code> to populate
            the ComponentManager.  One feature of the DefaultComponentManager is that
            it can cascade.  In other words, if the role is not found in this ComponentManager,
            the default implementation will look in the parent ComponentManager.
          </p>
          <p>
            For the paranoid developer, the cascading feature of the ComponentManager
            can be seen as a security hole as opposed to a usability enhancement.  You
            are free to create your own implementation that does not use the cascading
            feature--but you have to manually populate it with anything that would
            have been in the parent ComponentManager that your child Composable needs.
            Truth be told, there is very little risk due to the set-once contract for
            ComponentManagers.  The method is never exposed to hostile agents before
            the ComponentManager is set.
          </p>
        </section>
        <section>
  <title>DefaultComponentSelector</title>
          <p>
            The DefaultComponentSelector again is simply a Hashtable selection of components
            based on hints.  It gives the method <code>put</code> to populate the ComponentSelector.
            The ComponentSelector does not have the cascading feature of the ComponentManager,
            nor should it.  A ComponentSelector simply holds a number of components that
            implement the same role--there really is no need to cascade.
          </p>
          <p>
            After the ComponentSelector is populated, you must put it in the ComponentManager.
            Please use the role of the component you are selecting, not the role of the selector
            itself.  An acceptable convention is to add the "Selector" name to the end of the
            role you are looking up.  Just be consistent.
          </p>
        </section>
      </section>
      <section>
  <title>The Container</title>
      	<p>
  		The container is the entity that manages your components. It handles
  		things like loading of configuration files, resolution of dependencies,
  		component management, component isolation, and lifecycle support.
  	</p>
  	<p>
  		The container is not formalized in the form of an interface or contract
  		within Avalon Framework, though it might be at some point in the future.
  		The informal contract for the container is that it has the ability to
  		host any fully Avalon-Framework compliant component. Most current containers
  		place additional requirements on the component.
  	</p>
  	<p>
  		For a list of container implementations,
  		<link href="reference-containers.html">look here</link>.
  	</p>
      </section>
    </body>
  </document>
  
  
  
  1.1                  jakarta-avalon/src/xdocs/guide-cop-what-is.xml
  
  Index: guide-cop-what-is.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
  <document>
    <header>
      <title>Avalon Framework - Guide - What is COP?</title>
      <version>1.0</version>
      <authors>
        <person name="Leo Simons" email="leosimons@apache.org"/>
      </authors>
    </header>
    <body>
      <section>
  <title>Introduction</title> 
        <p>
          Component Oriented Programming, or COP for short, takes Object Oriented
          Programming one step further. Regular OOP organizes data objects into
          entities that take care of themselves. There are many advantages to this
          approach. I'll assume that you, being a Java programmer, are familiar
          with those.
        </p>
        <p>
          It also has a big limitation: that of object co-dependency. To remove that
          limitation, a more rigid idea had to be formalized: the component. The key
          difference between a regular object and a component is that a component is
          completely replaceable.
        </p>
      </section>
      <section>
  <title>COP is not just a Buzzword</title>
        <p>
          There is a lot of buzz in the industry touting Component Based Design
  	(CBD).  You will find, that the definition of a component in Avalon
  	is more formal than most companies' definition of a component.  Any
  	system developed with the principles of Avalon can claim CBD.  In
  	fact the Avalon Framework formalizes CBD more rigidly than the marketing
  	definition.  Do not be fooled though, CBD and COP aren't necessarily
  	the same thing.  Component Based Design refers to how a system is
  	designed and not how it is implemented.  Component Oriented Programming,
  	on the other hand, refers to how a system is implemented and not how
  	it is designed.  In practice, you can't implement COP without first
  	designing with components in mind.
        </p>
      </section>
    </body>
  </document>
  
  
  
  1.1                  jakarta-avalon/src/xdocs/guide-oop-best-practices.xml
  
  Index: guide-oop-best-practices.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
  <document>
    <header>
      <title>Avalon Framework - Guide - OOP best Practices</title>
      <authors>
        <person name="Leo Simons" email="leosimons@apache.org"/>
      </authors>
    </header>
    <body>
      <section>
  <title>Introduction</title>
        <p>
          While Avalon is not really about Object-Oriented Programming (OOP)
          (we go much further), some of its concepts are important in
          any programming project, so we summarise the 12 rules for code reuse
          as given in
          <link href="http://www.laputan.org/drc/drc.html">
            "Designing Reusable Classes"
          </link> by Ralph E. Johnson and Brian Foote (an excellent book).
        </p>
  
        <p>
          Note that a good knowledge of the basic OOP concepts is a requirement for
          understanding any of this. Many books deal with this, one that is freely
          available online is
          <link href="http://www.mindview.net/Books/TIJ/">
            "Thinking in Java"
          </link> by Bruce Eckel (also a recommended read).
        </p>
      </section>
      <section>
  <title>Recursion Introduction</title>
        <p>
          Use the same interface for communication with components of
          the same type.  It allows the swapping of those components
          for other components of the same type without breaking existing
          code.
        </p>
        <p>
          If you need additional functionality, either create proxy
          objects that implement the interface, or add it by subclassing
          (hence the name "Recursion Introduction").  Even if
          there is no recursion happening, it appears to operate in the
          same manner.
        </p>
      </section>
      <section>
  <title>Eliminate Case Analysis</title>
        <p>
          Avoid testing to see if an object is an instance of a particular
          class.  Usually, if you think you need that approach then a
          redesign will help immensely.
        </p>
      </section>
      <section>
  <title>Reduce the Number of Arguments</title>
        <p>
          Methods with a half-dozen arguments are hard to read, and can
          usually be accomplished with an object that represents that
          set of arguments.  It also makes it easier to track down the
          problems.
        </p>
      </section>
      <section>
  <title>Reduce the Size of Methods</title>
        <p>
          Most of your methods should only need to be a few lines long.
          Methods that are very long (like 50 lines or so) are too complex,
          and should be considered guilty of bad design until proven
          innocent.
        </p>
      </section>
      <section>
  <title>The Top of the Class Hierarchy Should be Abstract</title>
        <p>
          In many cases it is beneficial to provide an abstract base class 
          to extend for your specializations.  The majority of the 
          functionality and behavior is well defined. This makes it easier
          to decipher what the intents of the interface designer were.
        </p>
      </section>
      <section>
  <title>Minimize Accesses to Variables</title>
        <p>
          This point formalizes the principles of data hiding.  Try not
          to expose class attributes to other classes, but protect them
          by methods.  If an attribute changes name, then you only have
          one place to update the code instead of hundreds.
        </p>
      </section>
      <section>
  <title>Subclasses Should be Specializations</title>
        <p>
          A [subclass] "is a" [superclass].  If what you
          are trying to do is make a Component into a ComponentManager,
          then you are violating the spirit of the framework.  A better
          approach is to use containment in that case (i.e. a [class]
          "has a" [external class]).
        </p>
      </section>
      <section>
  <title>Split Large Classes</title>
        <p>
          If a class has 50+ methods, then it is most likely trying to
          do too much.  Look at separating the functionality into
          separate components.  Like methods that are too long, classes
          that violate this rule should be considered guilty of wrong
          design until proven innocent.
        </p>
      </section>
      <section>
  <title>Factor Implementation Differences Into Subcomponents</title>
        <p>
          If a subclass implements a method completely different from
          the superclass, then it is not really a specialization.  It
          should be split off from that class hierarchy tree.
        </p>
      </section>
      <section>
  <title>Separate Methods that Do Not Communicate</title>
        <p>
          Sometimes in building a framework you run into a case where
          you have different views of the same data.  In these cases,
          you can have some attributes that describe how to generate
          the data, and some attributes that describe the data itself.
          It is better to separate these two views into separate classes.
          The semantics are different enough to justify this solution.
        </p>
      </section>
      <section>
  <title>Send Messages to Components instead of to This</title>
        <p>
          The point of this point is that you want to build your framework
          based on components, and not inheritance.  Avalon takes this
          point to heart.  In order to illustrate, I will give two examples
          of the same thing.  The scenario is that we have a data structure
          that we want to output to an arbitrary format.
        </p>
        <p>
          In the following example, we will use the Java <code>this</code>
          object and an inheritance based framework.  As you can see, this
          would be a bear to maintain, and it won't easily be extended.
        </p>
        <source>
  abstract class AbstractExampleDocument 
  {
    // skip some code ...
  public void output(Example structure) 
  {
      if( null != structure )
      {
        this.format( structure );
      }
  }
  
    protected void format(Example structure);
  }
        </source>
        <p>
          In the next example, we will use the Avalon component based
          architecture.  There is a clean separation between the purpose
          of the objects, and you can exchange and extend formatting
          without worrying about any other concerns.
        </p>
        <source>
  class DefaultExampleDocument 
  {
  // skip some code ...
  public void output(Example structure) 
  {
     ExampleFormatter formatter = 
       (ExampleFormatter) manager.lookup(Roles.FORMATTER);
     if( null != structure ) 
     {
       formatter.format(structure);
     }
  }
  }
        </source>
        <p>
          An inheritance based framework (White Box) can be converted
          into a component based framework (Black Box) structure by
          replacing overridden methods with method calls (message sends)
          to components.  Component based architecture is much more
          flexible in this regard.
        </p>
      </section>
      <section>
  <title>Eliminate Implicit Parameter Passing</title>
        <p>
          Just because two methods share the same information within the
          class does not mean that it should be done in that manner.
          Many times, the attribute that is shared should be passed
          as a parameter of the method instead of directly accessing
          the attribute.
        </p>
      </section>
    </body>
  </document>
  
  
  
  1.1                  jakarta-avalon/src/xdocs/guide-patterns-in-avalon.xml
  
  Index: guide-patterns-in-avalon.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
  <document>
    <header>
      <title>Avalon Framework - Guide - Patterns in Avalon</title>
      <authors>
        <person name="Avalon Documentation Team" email="avalon-dev@jakarta.apache.org"/>
      </authors>
    </header>
    <body>
      <section>
  <title>Getting Started with Patterns</title>
        <p>
          Avalon takes many design patterns and architectural mindsets, and
          implements the best ones for servers.  There are different kinds of
          patterns that represent different aspects of Avalon. Avalon uses four
          main conceptual patterns called Separation of Interface and
          Implementation, Inversion of Control, Multi-Dimensional Separation
          of Concerns, and Aspect Oriented Programming.  Avalon also uses several
          architectural patterns like the Singleton and the Factory.
        </p>
      </section>
      <section>
  <title>The Avalon Patterns in short</title>
        <p>
          We provide you with a short description of the patterns first, with a
          detailed description of each pattern on a separate page.
        </p>
  
        <section>
  <title>Separation of Interface and Implementation</title>
          <p>
  <strong>Summary:</strong> The Separation of Interface and Implementation is
          a core feature of the Java language. However, it is often misused so we
          list it as one of the Avalon patterns, and our use of it is extensive.
          </p>
          <p>
  <link href="guide-patterns-soii.html">
            More Information...
          </link>
  </p>
        </section>
  
        <section>
  <title>Inversion of Control</title>
          <p>
  <strong>Summary:</strong> Avalon not only has an inheritance hierarchy, but also a
          component hierarchy. In this hierarchy, the control of program flow is
          completely in the hands of the parent component(s), as soldiers in the
          military take orders from their officers.
          </p>
          <p>
  <link href="guide-patterns-ioc.html">
            More Information...
          </link>
  </p>
        </section>
  
        <section>
  <title>Multi-Dimensional Separation of Concerns</title>
          <p>
  <strong>Summary:</strong> You just read the introduction about patterns before
          reading about Avalon's patterns because that enables you to reuse the
          knowledge you gained about patterns in a context other than that of
          Avalon. We do this with software as well.
          </p>
          <p>
  <link href="guide-patterns-soc.html">
            More Information...
          </link>
  </p>
        </section>
  
        <section>
  <title>Aspect-Oriented Programming</title>
          <p>
  <strong>Summary:</strong> this is the next logical step ofter Separation of
          Concerns. Many concerns cannot be centrally addressed using the standard
          OOP mechanisms. Using AOP (which is an extension to OOP), we would be
          able to do so in a simple fashion. As there is no good AOP facility
          in Java, we use "aspect marker interfaces" and COP instead.
          </p>
        </section>
  
        <section>
  <title>Component-Oriented Programming</title>
          <p>
  <strong>Summary:</strong> The Avalon framework promotes black-box reuse at
          every level. Doing so is commonly known as COP. This is so important
          in Avalon we devote an
          <link href="guide-cop-what-is.html">
          entire section
          </link>
          to it.
          </p>
        </section>
      </section>
  
    </body>
  </document>
  
  
  
  1.1                  jakarta-avalon/src/xdocs/guide-patterns-ioc-security.xml
  
  Index: guide-patterns-ioc-security.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
  <document>
    <header>
      <title>Avalon Framework - Guide - Security Concerns</title>
      <authors>
        <person name="Berin Loritsch" email="bloritsch@apache.org"/>
      </authors>
    </header>
    <body>
      <section>
  <title>Introduction</title>
        <p>
          One major concern for many companies is the security of a system.
          In this context security is defined as protection of data, and
          quality of service (QOS).  Both of these fall under security because
          a system must protect itself from these two forms of attack.  When
          a company loses a system, it loses business, and the money it
          loses can reach scary amounts.
        </p>
        <p>
          For the purpose of this discussion, we will address the first
          aspect (protection from crackers and system infiltration).  Many
          times, the same fixes for this type of protection inherently fix
          the other (QOS).  System security has three distinct concerns
          that have been well defined: authentication, authorization, and
          architecture.  Why didn't I say encryption?  It is because
          encryption does not equal security.  It is only part of the whole
  	system.
        </p>
        <section>
  <title>Authentication</title>
          <p>
            Authentication is the process of identifying parties.  In a completely
            trusted system, authentication is as simple as grabbing a reference
            to the object or entity you want to manipulate.  However, sometimes
            you have trusted systems running in hostile environments (e.g. the
            Internet).  In those cases you have to make sure that the entity
            is the correct one.
          </p>
          <p>
            There are two sides of authentication.  On one side, you are
            authenticating an entity you want to do business with.  On the other
            side, there is an entity wanting to do business with you.  This is
            best understood when you bring it into a financial realm.  Let's say
            you want to get a loan from XYZ bank.  If you initiate the exchange
            at their facility, you have already authenticated them--although you
            will have to jump through hoops to authenticate yourself.  If a
            telemarketer calls from ACME Loan Machine, Inc., they know who you
            are--although if you are smart, you will make them jump through
            hoops to authenticate themselves.
          </p>
          <p>
            Currently, Avalon identifies blocks as trusted parties.  In other
            words, the fact that they are installed correctly in the proper
            directory is enough to mark them as authenticated.  Much like a
            good friend--you know them by their voice.  Because of the architecture
            of Avalon, blocks define their own authentication system.  That
            means that whether the block assumes all components are trusted
            or it forces the blocks to authenticate themselves is up to the
            block.
          </p>
          <p>
            For systems that deal with sensitive information, authentication
            becomes more of an issue.  You must validate that the components
            in use are the ones you have authorized for use.  The more open a
            system is, the more authentication and authorization play an important
            role.  If you have components that are transmitted over some form
            of communications system (wire, air, etc.) you must verify that
            they are who they say they are.
          </p>
          <p>
            For this purpose, protocols like Kerberos and Leighton-Micali have
            been defined.  It is beyond the scope of this page to discuss the
            pros and cons of each system.
          </p>
        </section>
        <section>
  <title>Authorization</title>
          <p>
            Once a component has been authenticated (in other words its identity
            has been authoritatively validated), then you must decide what access
            it has to your systems.  A fully trusted component can do what it likes.
            An untrusted component must be denied functions it is not allowed.
          </p>
          <p>
            Authorization is part of the architecture, but is significant enough
            to warrant its own concern.  The best rule of thumb is to hide access
            to everything unless the component is trusted.  When hiding is not
            an option, then you have to resort to denying access.  For the security
            conscious, all denied accesses should be logged along with the component's
            identifier.
          </p>
        </section>
        <section>
  <title>Architecture</title>
          <p>
            Avalon already has the framework for the proper secure architecture.
            With proper planning, security can be added without recoding the components.
            However there are some rules of thumb for paranoid programming.
          </p>
          <ol>
            <li>
              Never expose anything that does not need to be exposed.  Information
              hiding is as important in security as it is in Component
              Oriented Programming (COP).
            </li>
            <li>
              Any component that originates from your own jar should be trusted--you
              provided it after all.
            </li>
            <li>
              Any component that originates from another source, and especially over
              a wire, should be treated with suspicion.  Authenticate it, and if it
              checks out, trust it.  Otherwise, don't give it access--you don't know
              where it's been or who created it.
            </li>
            <li>
              Encrypt <strong>all</strong> communications.  Period.
            </li>
          </ol>
        </section>
      </section>
      <section>
  <title>From the Sublime to the Ridiculous</title>
        <p>
          Throughout my short career I have been exposed to a wide range of security
          implementations.  Having worked for a DoD contractor, I learned about physical
          security requirements (how to manage paper files, and the rules and regulations
          regarding secure information).  However in a recent attempt to install a
          solution at our customer's site, I learned more about computer security
          than I have at any other time.
        </p>
        <p>
          Our customer, a well known corporation whom I will call ACME for
          anonymity, is in custody of sensitive information.  Product movement data,
          financial data, and demographic data are all stored in one of a couple of
          huge server farms.  Our application was to reside in the De-Militarized
          Zone (DMZ), and talk to a database behind the firewall.  When they discovered
          that the application server we chose required Remote Procedure Calls (the
          subject of many CERT advisories in the Unix world), we hit a brick wall.  Our
          application was no longer trusted, and was not to be installed.  Luckily
          the next version of the application server fixed that problem.
        </p>
        <p>
          In the midst of this, I decided to learn as much as I could about operating
          in a hardened environment.  Hardening involves turning off access to anything
          that is not needed, and only allowing what is needed.  All mail servers, ftp
          servers, rpc services, telnet, and any other clear text communications ports need
          to be removed.  All communication into and out of the box needs to be
          encrypted, with the exception of HTTP (although we were using HTTPS).
        </p>
        <p>
          All of this was necessary.  I understand the principles behind it.  However,
          I decided to ask their security analyst how to learn more--so we don't run
          into this problem again.  He gave me a link to
          <link href="http://www.sans.org">SANS institute</link> and a word of
          advice: "Be paranoid.  Don't trust anything."
        </p>
        <p>
          There is a point where the aforementioned philosophy goes a bit too far.  The
          case in point relates to a story I heard working with the DoD.  During the
          height of the "Cold War" between the US and Russia, a US commanding
          officer required that all the computers be placed on these huge power
          conditioners to reduce the Electro-Magnetic Interference (EMI) coming from the
          power line feedback of the computers.  His rationalization was that he was
  	positive KGB agents had the technology that they could read the EMI interference
  	on the power lines and read the bits on the computers.  In hindsight this is
  	improbable; no one can identify the bits travelling on a computer from EMI in the
  	power lines due to the level of noise (clocks, addressing lines,
  	<em>encrypted data</em>, and other computers on the network).
        </p>
        <p>
          The security industry has a general rule of thumb to ensure that you don't spend
  	too much time in this area:  The cost of cracking the server should be more than
  	the information that is protected is worth.  Basically it boils down to this:
  	sites like Slashdot and SourceForge do not require as much security as a bank.
  	Protecting free information is not as critical as protecting people's bank accounts.
  	I am not minimizing the contributions of the aforementioned sites to the world
  	as a whole, but people become much more agitated if their bank account is wiped
  	clean than if their news article is defaced.  This is not to say that if you are
  	protecting free information then you can safely ignore security.  While the information
  	is monetarily free to customers, it has value that can be measured in pride, respect,
  	and accountability.
        </p>
        <p>
          The moral of the story is be paranoid to a point.  Avalon is designed to be
          a trusted system, and will be improved to work in an untrusted network.
        </p>
      </section>
    </body>
  </document>
  
  
  
  1.1                  jakarta-avalon/src/xdocs/guide-patterns-ioc.xml
  
  Index: guide-patterns-ioc.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
  <document>
    <header>
      <title>Avalon Framework - Guide - Inversion of Control</title>
      <authors>
        <person name="Berin Loritsch" email="bloritsch@apache.org"/>
        <person name="Leo Simons" email="leosimons@apache.org"/>
      </authors>
    </header>
    <body>
      <section>
  <title>Introduction</title>
        <p>
          One of the key design principles behind Avalon is the principle
          of <em>Inversion of Control</em>.  <em>Inversion of Control</em> is
          a concept promoted by one of the founders of the Avalon project,
          <link href="mailto:stefano@apache.org">Stefano Mazzocchi</link>.  The
          principle enforces security by design.
        </p>
        <p>
          It is difficult to track down one paper that defines this pattern
          at length, so here are a couple of different definitions of
          <em>Inversion of Control</em>.
        </p>
      </section>
        <section>
  <title>What it Means</title>
          <p>
            The Framework plays the role of the main program in coordinating
            and sequencing events and application activity.
          </p>
          <p>
            A designer sets up a chain among objects that can all react
            to certain messages in a delegation hierarchy.  There is one
  	  major semantic detail: Inversion of Control refers to a parent
  	  object <em>controlling</em> a child object.  With this distinction,
  	  the SAX API is not considered Inversion of Control because its
  	  purpose is to send <em>information</em> from a source to a handler.
          </p>
          <section>
  <title>Definition by Analogy</title>
            <p>
              There are a couple of different analogies that make
              understanding <em>Inversion of Control</em> easier.  We
              experience this in many different ways in regular life,
              so we are borrowing the form in code.  One analogy is called
  	    the "Chain of Command" in the military.
            </p>
            <section>
  <title>Chain of Command</title>
              <p>
                This is probably the clearest parallel to <em>Inversion
                of Control</em>.  The military provides each new recruit
                with the basic things he needs to operate at his rank,
                and issues commands that recruit must obey.  The same
                principle applies in code.  Each component is given the
                provisions it needs to operate by the instantiating
                entity (i.e. Commanding Officer in this analogy).  The
                instantiating entity then acts on that component how it
                needs to act.
              </p>
  	    <p>
  	      There are some deficiencies in this analogy as some military
  	      or ex-military people have explained to me.  In the military,
  	      <strong>any</strong> Commanding Officer can issue commands to
  	      anyone under his or her rank.  In the development world, to
  	      ensure proper security, this is not a pattern you want in your
  	      software.  In Avalon, Inversion of Control (IoC) is from one
  	      parent (controlling) object to a child (controlled) component.
  	      A parent may have many children, but children only have one
  	      parent.
  	    </p>
            </section>
          </section>
        </section>
        <section>
  <title>How to Apply It</title>
          <p>
            <em>Inversion of Control</em> is applied in a very simple
            manner.  Basically, it means that the component architecture
            employs a <em>passive</em> structure.  See the following code:
          </p>
          <source>
  class MyComponent 
      implements LogEnabled
  {
      Logger logger;
  
      public enableLogging(Logger newLogger)
      {
          this.logger = newLogger;
      }
  
      myMethod() 
      {
          logger.info("Hello World!");
      }
  }
          </source>
          <p>
            The parent of MyComponent instantiates MyComponent, sets the
            Logger, and calls myMethod.  The component is not autonomous,
  	  and is given a logger that has been configured by the parent.
          </p>
          <p>
            The MyComponent class has no state apart from the parent, and
            has no way of obtaining a reference to the logger implementation
            without the parent giving it the implementation it needs.
          </p>
        </section>
        <section>
  <title>IOC promotes Security</title>
        <p>A big advantage of IOC for server applications is that it promotes
        security. You can read an analysis about this
        <link href="guide-patterns-ioc-security.html">
           here
        </link>.</p>
        </section>
    </body>
  </document>
  
  
  
  1.1                  jakarta-avalon/src/xdocs/guide-patterns-soc.xml
  
  Index: guide-patterns-soc.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
  <document>
    <header>
      <title>Avalon Framework - Guide - Multi Dimensional Separation of Concerns</title>
      <authors>
        <person name="Berin Loritsch" email="bloritsch@apache.org"/>
      </authors>
    </header>
    <body>
      <section>
  <title>Introduction</title>
        <p>
          The concept of using different points of view within the system
          goes a long way in the overall comprehension of the system.
        </p>
        <p>You can get more formal information in this paper:
          <link href="http://www.research.ibm.com/hyperspace/MDSOC.htm">Multi-Dimensional Separation of Concerns</link>.
        </p>
        <section>
  <title>What it Means</title>
          <p>
            "Separation of Concerns" in its simplest form is separating
            a problem into different points of view.  For instance, the documentation
            uses the "Separation of Concerns" pattern to make the documents
            comprehensible (we have separate documents for developers, administrators,
            and block implementers).  The documents also use the pattern with XML and
            XSL so that the look is separated from the content.  Either can change
            without breaking the other.
          </p>
          <p>
            This pattern is less clear to point out in the code, however the concept
            is evident.  There are several interfaces included in Avalon that identify 
            an object's role within the system.  For instance, all components have certain 
            contracts -- therefore any object that implements the Component interface 
            must comply with those contracts.  This allows developers to manipulate 
            components using a standard interface, without worrying about the semantics 
            of the implementation. They are separate concerns.
          </p>
        </section>
        <section>
  <title>How to Use It</title>
          <p>
            There are many ways to separate concern areas, but in Avalon
            we use interfaces to define the concern areas addressed in
            code.
          </p>
          <p>
            Every time you use interfaces within Object Oriented Programming (OOP),
            you are using the "Separation of Concerns" Pattern.  The interface
            separates the concern of the implementation from the concern of the user
            of the interface.  For example, every object that can be configured
            implements the Configurable interface.  The contract surrounding the
            Configurable interface is that the instantiator of the object passes a
            Configuration object to the Configurable object (see "Inversion
            of Control").  Just what the Configurable object does with the
            passed Configuration object is irrelevant to the instantiator.
          </p>
        </section>
      </section>
    </body>
  </document>
  
  
  
  1.1                  jakarta-avalon/src/xdocs/guide-patterns-soii.xml
  
  Index: guide-patterns-soii.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
  <document>
    <header>
      <title>Avalon Framework - Guide - Separation of Interface and Implementation</title>
      <authors>
        <person name="Paul Hammant" email="Paul_Hammant@yahoo.com"/>
        <person name="Peter Donald" email="peter at apache.org"/>
      </authors>
    </header>
    <body>
      <section>
  <title>Introduction</title>
        <p>
          The core concept of interface and implementation separation is built into
          Java itself in that it has interfaces and classes.  Many toolkits have
          been developed along the lines of an API / implementation separation.
          One such toolkit is the SAX API and the multiple XML parsers that implement
          it. Developers are quite happy using Apache's Xerces via the SAX API and
          understand that SAX represents the interface and Xerces an implementation.
          We notice that a lot of developers are happy to use interface/impl
          separated tools, but not to make them.  We will try to justify in this
          document why we think people making applications should define
          interface/impl boundaries early in the design cycle.
        </p>
        <section>
  <title>Justification</title>
          <p>
            The main reason we do it is because:
          </p>
            <ol>
                <li>it forces you to decouple different modules/components/objects</li>
                <li>if specified correctly allows you to easily change the implementation of
                    the interface/contract in the future</li>
                <li>makes it possible for a user to read documentation about the interface
                    without having the implementation details clutter up their perception</li>
                <li>increases the possibility of reuse in a larger application</li>
            </ol>
          <p>
            If you are building objects with the aim of reuse then [3] is important but
            most people don't build for reuse (and most XP advocates say you should just
            plan to use not reuse) and thus [1] and [2] are more important. If you feel
            like documenting that and expanding this then feel free to.
          </p>
        </section>
        <section>
  <title>Example</title>
          <p>
            Let us hope this is not necessary:
          </p>
  <source>
  package helloworld;
  public interface HelloWorld {
      void sayHello(String greeting);
  }
  
  package helloworld.impl.default;
  public class DefaultHelloWorld implements HelloWorld {
      void sayHello(String greeting) {
          System.out.println("HelloWorld Greeting: " + greeting);
      }
  }
  
  package helloworld.impl.remote;
  public class RemoteHelloWorld implements HelloWorld {
      private RemoteMessager mRemoteMessager;
      public RemoteHelloWorld(RemoteMessager rm) {
          RemoteMessager = rm;
      }
      void sayHello(String greeting) {
          rm.sendMessage("HelloWorld Greeting: " + greeting);
      }
  }
  </source>
  
        </section>
        <section>
  <title>History</title>
          <p>
            We are referring to this pattern as <strong>interface/impl separation</strong>.
            Wiley's Patterns in Java book refers to it simply as 'Interface', but we feel
            that the word interface is overloaded enough in English and computing.
          </p>
          <p>
            It might be true to say that this is 'API/implementation separation', but
            this too could be confusing as the aforementioned SAX is not quite a
            pure set of interfaces. It has a static factory that thunks in an
            implementation that all subsequent calls to the factory method will be
            forced to use. See Anti-Patterns below.
          </p>
          <p>
            Better might be 'separation of implementation and the interface/contract' as
            that is quite correct, but a tad unwieldy.
          </p>
        </section>
      </section>
      <section>
  <title>Related Topics</title>
        <section>
  <title>Implementation Hiding</title>
          <p>
            Once a tool is split into interface and impl, it is possible for a container
            to hide the implementation.  Most containers already use dynamic proxys
            (available in the JDK since 1.3), but we are talking about having the classes
            of the implementation hidden from classes using the interface.
          </p>
          <p>
            To do this, it is easiest to mount the impl classes in a separate classloader
            to the classloader that the interface-using classes are mounted in.  The
            interfaces being mounted in a classloader that is visible to both.
          </p>
          <p>
            This is not a new proposition.  Sun defined the servlet spec, and included
            rules about implementation hiding for hosted servlets.  Essentially,
            instantiated servlets are only allowed to 'see' classes from the JDK, their
            own WAR file and those of the Servlet API itself.  Tomcat correctly hides
            the implementation of the Servlet API from the hosted servlets.
          </p>
          <p>
            To actually achieve this separation, many containers (including those from
            the Avalon project) require that the interface and impl are in separate jars.
            Or to put it another way, there is no point separating your interface and impl
            classes if you are going to distribute them in the same jar.
          </p>
        </section>
        <section>
  <title>Kernel, Client API, Hosted Components</title>
          <p>
            This is building on the previous section, and in short is referred to as K/CAPI/HC.
            Basically the kernel mounts hosted components and satisfies their need for a
            client API. However the kernel wants to hide its implementation from the hosted
            components.
          </p>
          <p>
            An EJB container is another good example of this.  EntityBean, SessionBean etc. is
            the client API.  The hosted components are the beans, and the container has a
            kernel.  It builds a complex tree of classloaders to separate its implementation,
            the client API, the JDK's runtime jar (that always being in the system or
            primordial classloader), and the hosted components.
          </p>
          <p>
            The central message of this is that if you have interface/impl separated your
            tool, and are doing tricky things with more classloaders in the implementation,
            please make sure you do not assume that the parent classloader of any classloader
            is the system classloader.  If your reusable tool has been taken by another team
            and at some non root place in a classloader tree, then the tools will fail if
            you have made such assumptions.
          </p>
        </section>
        <section>
  <title>Anti-Patterns</title>
          <p>
            SAX, mentioned in multiple contexts in this document, is also an example of
            where the design can go wrong.  The Factory is static (that in itself is an
            anti-pattern to IoC).  Despite giving the appearance of having the ability
            to generate a parser based on the implementation's class name, only the first
            caller of that method will register a parser for the whole environment to use.
          </p>
          <p>
            Given that the SAX API is now in the JDK, the environment we allude to above
            is the whole JVM.  This is a problem because in a very complex application
            with differing concurrent needs for implementation of parsers, not all can be
            met if the SAX API is used for making parsers.
          </p>
        </section>
      </section>
    </body>
  </document>
  
  
  
  1.1                  jakarta-avalon/src/xdocs/guide-patterns-what-are.xml
  
  Index: guide-patterns-what-are.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
  <document>
    <header>
      <title>Avalon Framework - Guide - What are Design Patterns?</title>
      <authors>
        <person name="Berin Loritsch" email="bloritsch@apache.org"/>
        <person name="Leo Simons" email="leosimons@apache.org"/>
      </authors>
    </header>
    <body>
      <section>
  <title>Getting Started with Patterns</title>
        <p>
          I highly recommend reading the 
          <link href="http://www6.software.ibm.com/developerworks/education/j-patterns/index.html">
            "Java Design Patterns 101"
          </link> tutorial, and its follow-up
          <link href="http://www6.software.ibm.com/developerworks/education/j-patterns201/index.html">
            "Java Design Patterns 201"
          </link>, if you are unfamiliar with the concept of design patterns (and
          see below for more information). Note that you have to register at the
          IBM DeveloperWorks site in order to read these, but that's a good idea
          anyway.
        </p>
      </section>
      <section>
  <title>Where to Learn more</title>
        <p>
          You can find more information about patterns from the following links:
        </p>
        <ol>
          <li>Brian Foote's <link href="http://www.laputan.org/foote/papers.html">Pattern documents</link>
  </li>
          <li>
  <link href="http://www6.software.ibm.com/developerworks/education/j-patterns/index.html">
            "Java Design Patterns 101"
          </link> at DeveloperWorks</li>
  		<li>
  <link href="http://www6.software.ibm.com/developerworks/education/j-patterns201/index.html">
            "Java Design Patterns 201"
          </link> at DeveloperWorks</li>
  		<li>
  <link href="http://cseng.aw.com/book/0,3828,0201633612,00.html">
            "Java Design Patterns: Elements of Reusable Object-Oriented Software"
          </link> by the GoF (printed book)</li>
        </ol>
      </section>
    </body>
  </document>
  
  
  
  1.1                  jakarta-avalon/src/xdocs/guide-where-to-go-from-here.xml
  
  Index: guide-where-to-go-from-here.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
  <document>
    <header>
      <title>Avalon Framework - Guide - Where to Go next</title>
      <authors>
        <person name="Leo Simons" email="leosimons@apache.org"/>
      </authors>
    </header>
    <body>
      <section>
  <title>There's a lot more to study</title>
        <p>
          Each of the pages in this short guide deserves an entire book, and
          indeed, most of them have a lot of documentation devoted to them.
          Here we provide you with pointers where else to look for more
          information, within and outside of Avalon.
        </p>
      </section>
      <section>
  <title>Creating Components</title>
        <p>
          After all the information in this guide has sunk in, you're probably
          itching to write an Avalon component. Our
          <link href="http://avalon.apache.org/developing/index.html">Developing with Avalon guide
          </link> takes you through doing just that. You can download it as a PDF
          and read at your leisure (it comes down to 56 printed pages). If that's
          too much for you, we suggest you get the latest
          <link href="http://avalon.apache.org/excalibur/index.html">Excalibur</link> release and
          take those components as an example. One application that uses a lot of
          those components and is in widespread daily use is
          <link href="http://xml.apache.org/cocoon">Cocoon</link>.
        </p>
      </section>
    </body>
  </document>
  
  
  
  1.21      +77 -111   jakarta-avalon/src/xdocs/index.xml
  
  
  
  
  1.1                  jakarta-avalon/src/xdocs/reference-containers.xml
  
  Index: reference-containers.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
  <document>
    <header>
      <title>Avalon Framework - Containers</title>
      <authors>
        <person id="PH" name="Paul Hammant" email="Paul_Hammant@yahoo.com"/>
        <person name="Leo Simons" email="leosimons@apache.org"/>
      </authors>
    </header>
    <body>
      <section>
  <title>Introduction</title>
        <p>
          There are various containers that are aware of the Avalon Framework interfaces.
  	This is a sort-of comprehensive list.
        </p>
      </section>
      <section>
  <title>Standalone Containers</title>
        <p>
          These typically run from the command line and are launched via a legacy main() method.
        </p>
        <section>
  <title>Avalon Phoenix</title>
          <p>
            This is a sister project to Avalon Framework.  It provides an environment
            for launching multiple, isolated, more or less unrestricted server applications
  	  as hosted components.  These can be applications like a web server, RDBMS or
  	  EJB server. It provides many advanced features like automatic management, at the
  	  cost of a bit of complexity.
            See <link href="http://avalon.apache.org/phoenix/index.html">Phoenix</link>.
          </p>
  
  	<p>
  	  Phoenix is the oldest of the Avalon Containers; it is probably the most powerful
  	  and most widely used. While still in alpha, this hints at the fact that we find it
  	  to be not completely future complete, rather than an infantile project.
  	</p>
        </section>
  
  	<section>
  <title>Avalon Excalibur's Tweety</title>
  	<p>
  	Tweety is almost the opposite of Phoenix. It is a recent development and written
  	exclusively as a teaching tool. It has no features whatsoever besides basic support
  	for the Avalon lifecycle. This results in a complete distribution the size of the
  	Phoenix bootstrapper.
  	See <link href="http://avalon.apache.org/excalibur/tweety">Tweety</link>
  	</p>
  	</section>
  
  	<section>
  <title>Myrmidon</title>
  	<p>
  	Myrmidon is a proposal for the kernel of
  	<link href="http://jakarta.apache.org/ant">Apache Ant</link> 2.
  	See <link href="http://cvs.apache.org/viewcvs.cgi/jakarta-ant/proposal/myrmidon/">Myrmidon</link>
  	</p>
  	</section>
      </section>
      <section>
  <title>Embedded Containers</title>
        <p>
          These run inside another application (like a servlet engine) and are controlled by it.
        </p>
        <section>
  <title>Excalibur Component Manager</title>
          <p>
            This is used by various applications like Cocoon. Cocoon is run inside the
            Sun specified servlet context of a web-app.  It is designed for such
            servlet-context reuse. ECM is the most stable of the containers (it is the
  	  only one with a stable release); it is also arguably the worst design.
  	  See <link href="http://avalon.apache.org/excalibur/component/">ECM</link>.
          </p>
        </section>
        <section>
  <title>Fortress</title>
          <p>
            Fortress is meant as a future replacement of ECM. It fixes several of ECMs flaws
  	  like a mixup of concerns. It is built to be very extensible, and it includes
  	  support for custom lifecycle extensions. Fortress is still pre-alpha.
  	  See <link href="http://avalon.apache.org/excalibur/fortress/">Fortress</link>.
          </p>
        </section>
        <section>
  <title>Merlin</title>
          <p>
            Another recent development is Merlin, which has a client API very similar to
  	  Phoenix (applications that can run within phoenix can run within merlin as
  	  well). Merlin is still pre-alpha.
  	</p>
  	<p>
  	  See <link href="http://home.osm.net/doc/merlin/index.html">Merlin</link>.
          </p>
        </section>
        <section>
  <title>Plexus</title>
          <p>
            Plexus is a container under development that will become the basis of the
  	  services framework for a sister project to Avalon,
  	  <link href="http://jakarta.apache.org/turbine">Turbine</link>.
          </p>
  	<p>
  		See <link href="http://tambora.zenplex.org/cgi-bin/cvsweb.cgi/plexus/">Plexus</link>.
  	</p>
  	<note>
  	Plexus is being developed outside of Avalon itself as an external project.
  	</note>
        </section>
        <section>
  <title>Enterprise Object Broker (EOB)</title>
          <p>
            The reference implementation of this EJB-replacement container runs on top of
            Phoenix.  EOB supports a subset of the Avalon Framework interfaces but allows
            RPC publishing of arbitary interfaces apparent in a hosted components object
            model.
          </p>
  	<p>
  		  See <link href="http://eob.sourceforge.net/">EOB</link>.
  	</p>
  	<note>
  	EOB is an being developed outside of Avalon itself as an external project.
  	</note>
        </section>
       </section>
    </body>
  </document>
  
  
  
  1.1                  jakarta-avalon/src/xdocs/reference-the-lifecycle.xml
  
  Index: reference-the-lifecycle.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
  <document>
    <header>
      <title>Avalon Framework - The Component Lifecycle</title>
      <authors>
        <person id="BL" name="Berin Loritsch" email="bloritsch@apache.org"/>
        <person id="PD" name="Peter Donald" email="peter at apache.org"/>
        <person id="LS" name="Leo Simons" email="mail@leosimons.com"/>
      </authors>
    </header>
    <body>
      <section>
  <title>Introduction</title>
        <p>
          A component lives within something called a container. The contract between a 
          container and a contained component is simple: the container is required to 
          take a component through what is called its <strong>lifecycle</strong>.
        </p>
        <p>
          The Avalon project provides an
          application that functions as a container for componentized applications 
          called <link href="http://avalon.apache.org/phoenix/index.html">Phoenix</link>.  This is not 
          exclusive, components adhering to lifecycle interfaces, can be mounted in 
          custom containers.  Cocoon and others mounts their own containers for 
          components and invoke relevant methods from the lifecycle interfaces.  See
          <link href="reference-containers.html">Containers</link>.
        </p>
        <p>
          The lifecyle methods from the Avalon Framework sub-project are designed to be
          used by just about any component hosted by any container.  Of course, the API
          in question may well require additional interfaces for strongly typed 
          functionality, but these interfaces should negate the need for any duplication
          of effort.
        </p>
      </section>
      <section>
  <title>The Lifecycle</title>
        <p>
          The lifecycle of a component specifies the methods that can be called on it,
          and the order in which this may happen. Some methods can be called only once
          in a specific <code>phase</code> of a component's lifecycle, others may
          be called multiple times. These methods are called the lifecycle methods.
        </p>
        <p>
          It is up to each container to indicate which lifecycle methods it will honor.
          This should be clearly documented together with the description of the
          container. A sister project to Phoenix supports all of the lifecycle methods defined in the
          Avalon Framework API.
        </p>
      </section>
      <section>
  <title>The Lifecycle Interfaces</title>
        <p>
          A component exposes its lifecycle methods by implementing the lifecycle
          interfaces. Each of these defines one or more methods that represent a
          specific phase in a component's lifecycle. The defined interfaces are:
        </p>
        <ol>
          <li>LogEnabled</li>
          <li>Contextualizable</li>
          <li>Serviceable (replacement for Composable)</li>
          <li>Configurable</li>
          <li>Parameterizable</li>
          <li>Initializable</li>
          <li>Startable</li>
          <li>Suspendable</li>
          <li>Recontextualizable</li>
          <li>Recomposable</li>
          <li>Reconfigurable</li>
          <li>Reparameterizable</li>
          <li>Stoppable</li>
          <li>Disposable</li>
        </ol>
        <note>
          <strong>Note:</strong>java.lang.Runnable has also been in use as a lifecycle
          interface. This is not recommended and is not supported by Avalon. Instead,
          the run() method is the responsibility of the component itself. If you wish
          to use it, call it from within start() or another method.  
        </note>
      </section>
      <section>
  <title>Phase Order</title>
        <p>
          The order in which the various lifecycle methods are called is very specific.
          While none are required (it is possible to have a component implementing
          none of the lifecycle methods, although the use of that would be limited),
          some can only be used when others are as well. This is best explained using
          a few examples.
        </p>
        <section>
  <title>Simple Examples</title>
          <p>The lifecycle of a component implementing only Configurable for
          example will be:</p>
          <ol>
            <li>constructor</li>
            <li>configure</li>
            <li>finalize</li>
          </ol>
          <p>The lifecycle of a component implementing only Serviceable will be:</p>
          <ol>
            <li>constructor</li>
            <li>service</li>
            <li>finalize</li>
          </ol>
        </section>
        <section>
  <title>Complete</title>
          <p>
            If a component implements more than one interface the order of
            the events (service, configure etc.) follow a specific order. A component
            implementing all above interfaces (including Runnable) will follow these
            specific paths.
          </p>
          <p>
            Startup Phase:
          </p>
          <ol>
            <li>constructor <strong>as a consequence of instantiation</strong>
  </li>
            <li>contextualize</li>
            <li>service or compose</li>
            <li>configure</li>
            <li>parameterize</li>
            <li>initialize</li>
            <li>start</li>
          </ol>
          <p>
            At various or repeated times after startup:
          </p>
          <ol>
            <li>suspend</li>
            <li>recontextualize</li>
            <li>recompose</li>
            <li>reconfigure</li>
            <li>reparameterize</li>
            <li>resume</li>
          </ol>
          <p>
            Shutdown Phase:
          </p>
          <ol>
            <li>stop</li>
            <li>dispose</li>
            <li>finalize <strong>at some indeterminate moment by the garbage collector</strong>
  </li>
          </ol>
        </section>
        <section>
  <title>Phases executed once</title>
          <p>
            These lifecycle methods are only called once in the entire life of a
            component:
          </p>
          <ul>
            <li>contextualize</li>
            <li>service</li>
            <li>configure</li>
            <li>parameterize</li>
            <li>initialize</li>
            <li>dispose</li>
          </ul>
        </section>
        <section>
  <title>Phases executed once or more</title>
          <p>
            These lifecycle methods are called at least once and possibly more, depending
            on the container:
          </p>
          <ul>
            <li>start</li>
            <li>stop</li>
          </ul>
        </section>
        <section>
  <title>The Suspendable Interface</title>
          <p>
            The methods suspend() and resume() are not guaranteed to be called at all,
            even when implemented. They can be called more than once, but only after
            one another and between start() and stop(). The reason they exist is so 
            the container can notify the component it needs to temporarily stop 
            any operations. The container may need to perform some synchronized operation 
            on one of the components used by this component, or it may wish to call any 
            of the following methods, which can also be called zero or more times, and 
            only between a suspend() and a resume().
          </p>
          <ul>
            <li>recontextualize()</li>
            <li>recompose()</li>
            <li>reconfigure()</li>
            <li>reparameterize()</li>
          </ul>
        </section>
      </section>
    </body>
  </document>
  
  
  
  1.1                  jakarta-avalon/src/xdocs/tabs.xml
  
  Index: tabs.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
        <!DOCTYPE tabs PUBLIC "-//APACHE//DTD Cocoon Documentation Tab V1.0//EN" "tab-cocoon-v10.dtd">
  
        <tabs software="MyProj"
          title="MyProj"
          copyright="Foo"
          xmlns:xlink="http://www.w3.org/1999/xlink">
  
          <tab label="Avalon Home" href="http://avalon.apache.org/"/>
          <tab label="Framework" dir=""/>
          <tab label="Components" href="http://avalon.apache.org/components/"/>
          <tab label="Phoenix" href="http://avalon.apache.org/phoenix/"/>
          <tab label="SECA" href="http://avalon.apache.org/seca/"/>
          <tab label="Apps" href="http://avalon.apache.org/apps/"/>
      </tabs>
  
  

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


Mime
View raw message