avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From blorit...@apache.org
Subject cvs commit: avalon-site/site/excalibur/fortress using-meta-info.html cli.html design-notes.html features.html getting-started.html index.html lifecycle-extensions.html servlet.html swing.html
Date Fri, 30 May 2003 19:50:40 GMT
bloritsch    2003/05/30 12:50:40

  Modified:    site/excalibur/fortress cli.html design-notes.html
                        features.html getting-started.html index.html
                        lifecycle-extensions.html servlet.html swing.html
  Added:       site/excalibur/fortress using-meta-info.html
  Log:
  update the docs
  
  Revision  Changes    Path
  1.3       +4 -0      avalon-site/site/excalibur/fortress/cli.html
  
  Index: cli.html
  ===================================================================
  RCS file: /home/cvs/avalon-site/site/excalibur/fortress/cli.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- cli.html	21 May 2003 19:29:13 -0000	1.2
  +++ cli.html	30 May 2003 19:50:40 -0000	1.3
  @@ -74,6 +74,10 @@
   </div>
               
   <div class="menuItem">
  +<a href="using-meta-info.html"></a>
  +</div>
  +            
  +<div class="menuItem">
   <a href="http://jakarta.apache.org/builds/avalon-excalibur/release">Download</a>
   </div>
           
  
  
  
  1.3       +4 -0      avalon-site/site/excalibur/fortress/design-notes.html
  
  Index: design-notes.html
  ===================================================================
  RCS file: /home/cvs/avalon-site/site/excalibur/fortress/design-notes.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- design-notes.html	21 May 2003 19:29:13 -0000	1.2
  +++ design-notes.html	30 May 2003 19:50:40 -0000	1.3
  @@ -74,6 +74,10 @@
   </div>
               
   <div class="menuItem">
  +<a href="using-meta-info.html"></a>
  +</div>
  +            
  +<div class="menuItem">
   <a href="http://jakarta.apache.org/builds/avalon-excalibur/release">Download</a>
   </div>
           
  
  
  
  1.3       +8 -1      avalon-site/site/excalibur/fortress/features.html
  
  Index: features.html
  ===================================================================
  RCS file: /home/cvs/avalon-site/site/excalibur/fortress/features.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- features.html	21 May 2003 19:29:13 -0000	1.2
  +++ features.html	30 May 2003 19:50:40 -0000	1.3
  @@ -74,6 +74,10 @@
   </div>
               
   <div class="menuItem">
  +<a href="using-meta-info.html"></a>
  +</div>
  +            
  +<div class="menuItem">
   <a href="http://jakarta.apache.org/builds/avalon-excalibur/release">Download</a>
   </div>
           
  @@ -222,7 +226,10 @@
             and generates the meta info files which are then read at
             runtime.  It makes it a whole lot easier to manage critical
             aspects like lifestyle and which classes represent components.
  -        </p>
  +          <a href="using-meta-info.html">You can find out more about it
  +          here.</a>
  +        
  +</p>
         
       
     
  
  
  
  1.3       +5 -1      avalon-site/site/excalibur/fortress/getting-started.html
  
  Index: getting-started.html
  ===================================================================
  RCS file: /home/cvs/avalon-site/site/excalibur/fortress/getting-started.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- getting-started.html	21 May 2003 19:29:13 -0000	1.2
  +++ getting-started.html	30 May 2003 19:50:40 -0000	1.3
  @@ -74,6 +74,10 @@
   </div>
               
   <div class="menuItem">
  +<a href="using-meta-info.html"></a>
  +</div>
  +            
  +<div class="menuItem">
   <a href="http://jakarta.apache.org/builds/avalon-excalibur/release">Download</a>
   </div>
           
  @@ -174,7 +178,7 @@
                   
   <li>Check out the modules avalon, avalon-excalibur,
                   avalon-logkit and jakarta-site</li>
  -    
  +                
   <li>Use ant to build the various projects: avalon, logkit, excalibur fortress.
                   If something goes wrong, run ant in verbose mode using the -v option and
                   send the output to the avalon-user mailing list. Someone'll help you out.
  
  
  
  1.3       +6 -13     avalon-site/site/excalibur/fortress/index.html
  
  Index: index.html
  ===================================================================
  RCS file: /home/cvs/avalon-site/site/excalibur/fortress/index.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- index.html	21 May 2003 19:29:13 -0000	1.2
  +++ index.html	30 May 2003 19:50:40 -0000	1.3
  @@ -74,6 +74,10 @@
   </div>
               
   <div class="menuItem">
  +<a href="using-meta-info.html"></a>
  +</div>
  +            
  +<div class="menuItem">
   <a href="http://jakarta.apache.org/builds/avalon-excalibur/release">Download</a>
   </div>
           
  @@ -152,17 +156,6 @@
   <h3>Introduction</h3>
   </div>
         
  -<div class="frame warning">
  -<div class="label">Warning</div>
  -<div class="content">
  -        This package is under development, and the API is not
  -        guaranteed to be the same when it is ready for release.
  -        You can find this in the excalibur-fortress-1.0.jar file if you want
  -        to play with it. Do not blame us if the next release of
  -        Excalibur breaks your code if you use this package.
  -      </div>
  -</div>
  -      
   <p>
           Fortress contains a framework to help you create your own
           avalon containers.  It boasts asynchronous management of your
  @@ -173,7 +166,7 @@
       
       
   <div class="h3">
  -<h3>downloads</h3>
  +<h3>Downloads</h3>
   </div>
           
   <p>
  @@ -188,7 +181,7 @@
       
       
   <div class="h3">
  -<h3>available documentation</h3>
  +<h3>Available Documentation</h3>
   </div>
           
   <ul>
  
  
  
  1.3       +4 -0      avalon-site/site/excalibur/fortress/lifecycle-extensions.html
  
  Index: lifecycle-extensions.html
  ===================================================================
  RCS file: /home/cvs/avalon-site/site/excalibur/fortress/lifecycle-extensions.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- lifecycle-extensions.html	21 May 2003 19:29:13 -0000	1.2
  +++ lifecycle-extensions.html	30 May 2003 19:50:40 -0000	1.3
  @@ -74,6 +74,10 @@
   </div>
               
   <div class="menuItem">
  +<a href="using-meta-info.html"></a>
  +</div>
  +            
  +<div class="menuItem">
   <a href="http://jakarta.apache.org/builds/avalon-excalibur/release">Download</a>
   </div>
           
  
  
  
  1.3       +4 -0      avalon-site/site/excalibur/fortress/servlet.html
  
  Index: servlet.html
  ===================================================================
  RCS file: /home/cvs/avalon-site/site/excalibur/fortress/servlet.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- servlet.html	21 May 2003 19:29:13 -0000	1.2
  +++ servlet.html	30 May 2003 19:50:40 -0000	1.3
  @@ -74,6 +74,10 @@
   </div>
               
   <div class="menuItem">
  +<a href="using-meta-info.html"></a>
  +</div>
  +            
  +<div class="menuItem">
   <a href="http://jakarta.apache.org/builds/avalon-excalibur/release">Download</a>
   </div>
           
  
  
  
  1.3       +4 -0      avalon-site/site/excalibur/fortress/swing.html
  
  Index: swing.html
  ===================================================================
  RCS file: /home/cvs/avalon-site/site/excalibur/fortress/swing.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- swing.html	21 May 2003 19:29:13 -0000	1.2
  +++ swing.html	30 May 2003 19:50:40 -0000	1.3
  @@ -74,6 +74,10 @@
   </div>
               
   <div class="menuItem">
  +<a href="using-meta-info.html"></a>
  +</div>
  +            
  +<div class="menuItem">
   <a href="http://jakarta.apache.org/builds/avalon-excalibur/release">Download</a>
   </div>
           
  
  
  
  1.1                  avalon-site/site/excalibur/fortress/using-meta-info.html
  
  Index: using-meta-info.html
  ===================================================================
  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  <html>
  <head>
  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  <!--*** This is a generated file.  Do not edit.  ***-->
  <link rel="stylesheet" href="skin/tigris.css" type="text/css">
  <link rel="stylesheet" href="skin/mysite.css" type="text/css">
  <link rel="stylesheet" href="skin/site.css" type="text/css">
  <link media="print" rel="stylesheet" href="skin/print.css" type="text/css">
  <title>Excalibur Fortress - Using Meta Info</title>
  </head>
  <body bgcolor="white" class="composite">
  <!--================= start Banner ==================-->
  <div id="banner">
  <table width="100%" cellpadding="8" cellspacing="0" summary="banner" border="0">
  <tbody>
  <tr>
  <!--================= start Group Logo ==================-->
  <td align="left">
  <div class="groupLogo">
  <a href="http://www.apache.org/"><img border="0" class="logoImage" alt="Apache"
src="images/group-logo.gif"></a>
  </div>
  </td>
  <!--================= end Group Logo ==================-->
  <!--================= start Project Logo ==================--><td align="right">
  <div class="projectLogo">
  <a href="http://avalon.apache.org/"><img border="0" class="logoImage" alt="Apache
Avalon" src="images/project-logo.gif"></a>
  </div>
  </td>
  <!--================= end Project Logo ==================-->
  </tr>
  </tbody>
  </table>
  </div>
  <!--================= end Banner ==================-->
  <!--================= start Main ==================-->
  <table width="100%" cellpadding="0" cellspacing="0" border="0" summary="nav" id="breadcrumbs">
  <tbody>
  <!--================= start Status ==================-->
  <tr class="status">
  <td>
  <!--================= start BreadCrumb ==================--><a href=""></a><a
href=""></a><a href=""></a>
  <!--================= end BreadCrumb ==================--></td><td id="tabs">
  <!--================= start Tabs ==================-->
  <div class="tab">
  <span class="unselectedTab"><a href="http://avalon.apache.org/">Avalon Home</a></span>
| <span class="selectedTab"><a href="index.html"><font color="#000000">Framework</font></a></span>
| <span class="unselectedTab"><a href="http://avalon.apache.org/components/">Components</a></span>
| <span class="unselectedTab"><a href="http://avalon.apache.org/phoenix/">Phoenix</a></span>
| <span class="unselectedTab"><a href="http://avalon.apache.org/seca/">SECA</a></span>
  </div>
  <!--================= end Tabs ==================-->
  </td>
  </tr>
  </tbody>
  </table>
  <!--================= end Status ==================-->
  <table id="main" width="100%" cellpadding="8" cellspacing="0" summary="" border="0">
  <tbody>
  <tr valign="top">
  <!--================= start Menu ==================-->
  <td id="leftcol">
  <div id="navcolumn">
  <div class="menuBar">
  <div class="menu">
  <span class="menuLabel">Essentials</span>
              
  <div class="menuItem">
  <a href="index.html">Overview</a>
  </div>
              
  <div class="menuItem">
  <a href="features.html">Features</a>
  </div>
              
  <div class="menuItem">
  <a href="getting-started.html">Getting Started</a>
  </div>
              
  <div class="menuItem">
  <span class="menuSelected"></span>
  </div>
              
  <div class="menuItem">
  <a href="http://jakarta.apache.org/builds/avalon-excalibur/release">Download</a>
  </div>
          
  </div>
  <div class="menu">
  <span class="menuLabel">Environments</span>
              
  <div class="menuItem">
  <a href="cli.html">Command Line Applications</a>
  </div>
              
  <div class="menuItem">
  <a href="swing.html">Swing Applications</a>
  </div>
              
  <div class="menuItem">
  <a href="servlet.html">Servlet Applications</a>
  </div>
          
  </div>
  <div class="menu">
  <span class="menuLabel">Related</span>
              
  <div class="menuItem">
  <a href="http://jakarta.apache.org/avalon/">Avalon Home</a>
  </div>
              
  <div class="menuItem">
  <a href="http://jakarta.apache.org/avalon/excalibur/">Excalibur Home</a>
  </div>
              
  <div class="menuItem">
  <a href="http://jakarta.apache.org/avalon/phoenix">Avalon Phoenix</a>
  </div>
              
  <div class="menuItem">
  <a href="http://jakarta.apache.org/avalon/excalibur/component">ECM</a>
  </div>
              
  <div class="menuItem">
  <a href="http://jakarta.apache.org/avalon/excalibur/tweety">Tweety</a>
  </div>
          
  </div>
  <div class="menu">
  <span class="menuLabel">Reference</span>
              
  <div class="menuItem">
  <a href="http://avalon.apache.org/api/">API Docs</a>
  </div>
              
  <div class="menuItem">
  <a href="lifecycle-extensions.html">Lifecycle Extensions</a>
  </div>
              
  <div class="menuItem">
  <a href="design-notes.html">Design Notes</a>
  </div>
          
  </div>
  </div>
  </div>
  </td>
  <!--================= end Menu ==================-->
  <!--================= start Content ==================--><td>
  <div id="bodycol">
  <div class="app">
  <div align="center">
  <h1>Excalibur Fortress - Using Meta Info</h1>
  </div>
  <div class="h3">
      
      
          
  <div class="h3">
  <h3>What is Meta Information?</h3>
  </div>
              
              
  <p>
                  Meta Information is information about your components.  The information
that
                  Fortress needs to properly manage your components is fairly small.  It needs
to
                  know which classes are components, which services that component implements,
what
                  its dependencies are, and what type of lifestyle the component was designed
for.
                  Using this information, Fortress can determine if there are some circular
                  dependencies as well as manage other aspects of your component.
              </p>
              
  <p>
                  Your container has to find the meta information in some way.  If you are
used
                  to the Excalibur Component Manager (ECM), then you supplied the meta information
                  based on a "roles" file and certain marker interfaces that your component
                  implemented.  There are several drawbacks to this approach, some of which
include
                  inheritance of conflicting meta information and having to manage your information
                  in separate files.
              </p>
              
  <p>
                  Fortress has adopted a practice that is available in both Phoenix and Merlin
to
                  make managing meta information a breeze.  It is the use of JavaDoc tags
to mark the
                  meta information right with the source code itself.  This scheme works much
better,
                  and unlocks some features to you.  One of them is for Fortress to tell you
that you
                  have a circular dependency (some components that require each other to work)
at
                  initialization time instead of at run time.
              </p>
          
          
  <div class="h3">
  <h3>How does the Meta Info Tags Look?</h3>
  </div>
              
              
  <p>
                  The best way to demonstrate how these tags look and behave is to show some
sample
                  code.  Fortress follows the AMTAGS proposal on the WIKI, and also supports
a couple
                  extra tags.  Specifically, the set of tags that Fortress supports are
                  "avalon.dependency", "avalon.service", "x-avalon.info", "x-avalon.lifestyle",
                  "avalon.component", "fortress.name", "fortress.handler".  The two Fortress
specific
                  tags are recognized, but are not encouraged for routine use.
              </p>
              
  <p>
                  Everything except for the "avalon.dependency" must be specified in the component's
                  class JavaDoc.  Below is a snippet:
              </p>
              
  <pre class="code">
                  
  /**
   * My component implementation.
   *
   * @avalon.component
   * @avalon.service type="RoleInterface"
   * @x-avalon.info name="my-component"
   * @x-avalon.lifestyle type="pooled"
   */
  public class MyComponent implements RoleInterface
  {
      // ....
  }
                  
              </pre>
              
  <p>
                  The "avalon.component" is a marker tag, and it is required to mark a class
as a
                  component.  You must have one or more "avalon.service" tags (one per interface
                  type).  The value in the "type" attribute must be a resolvable class name.
 If the
                  type of "RoleInterface" is in the same package, or in one of the imports,
then all
                  is well.  The "x-avalon.info" tag is used to provide a configuration name
for the
                  component.  In this case, the configuration name is "my-component".  If
you do not
                  supply this tag, Fortress will create one for you based on the class name
of the
                  component.  It is best if you supply your own.  The "x-avalon.lifestyle"
tag is
                  used to choose how this component is managed.
              </p>
              
  <p>
                  Dependencies are declared in the <span class="codefrag">service()</span>
method for the component.
                  The component needs to implement the Serviceable interface.  Fortress knows
how
                  to look at the code hierarchy to collect all the dependencies as long as
you have
                  all your source code available.  The dependency declarations look like this:
              </p>
              
  <pre class="code">
                  
  /**
   * Get all the dependencies.
   *
   * @avalon.dependency type="OtherService"
   * @avalon.dependency type="Foo"
   */
  public void service( ServiceManager manager )
  {
      // ...
  }
                  
              </pre>
              
  <p>
                  All the "avalon.dependency" entries are collected by the same rules as the
                  "avalon.service" entries.  In other words, the "type" attribute is evaluated
                  based on the same rules as your Java compiler evaluates them.  Fortress
will
                  take care of resolving them properly.
              </p>
          
          
  <div class="h3">
  <h3>Collecting the Meta Information</h3>
  </div>
              
              
  <p>
                  Fortress provides an ANT task to collect all your meta information and generate
                  the extra files that your JAR files need to have for Fortress to use the
meta
                  information at run time.  You include the ANT task in your build.xml file
like
                  this:
              </p>
              
  <pre class="code">
                  
  &lt;project&gt;
    &lt;!-- ... --&gt;
  
    &lt;taskdef name="collect-metainfo"
             classname="org.apache.avalon.fortress.tools.ComponentMetaInfoCollector"&gt;
      &lt;classpath refid="tools.class.path"/&gt;
    &lt;/taskdef&gt;
  
    &lt;target name="compile" depends="jar-tools" description="Compiles the source code"&gt;
      &lt;mkdir dir="${build.classes}"/&gt;
  
      &lt;!-- Compile all classes excluding the tests. --&gt;
      &lt;javac srcdir="${java.dir}"
             destdir="${build.classes}"&gt;
        &lt;classpath&gt;
          &lt;path refid="tools.class.path"/&gt;
          &lt;pathelement location="${loader.classes}"/&gt;
        &lt;/classpath&gt;
        &lt;include name="**/*.java"/&gt;
      &lt;/javac&gt;
  
      &lt;collect-metainfo destdir="${build.classes}"&gt;
        &lt;fileset dir="${java.dir}"/&gt;
      &lt;/collect-metainfo&gt;
    &lt;/target&gt;
  
    &lt;!-- ... --&gt;
  &lt;/project&gt;
                  
              </pre>
              
  <p>
                  Once you include all the generated files in your JAR for the components,
you
                  don't have to do anything more than include the JAR in your classpath for
Fortress.
                  Everything else is taken care of.
              </p>
          
          
  <div class="h3">
  <h3>The x-avalon.lifestyle Tag</h3>
  </div>
              
              
  <p>
                  The "x-avalon.lifestyle" tag needs a little further explanation.  It can
have one
                  of four values in the "type" attribute:
              </p>
              
  <ul>
                  
  <li>
  <strong>singleton</strong> One instance of the component shared with all clients.</li>
                  
  <li>
  <strong>thread</strong> One instance of the component per thread of execution.</li>
                  
  <li>
  <strong>pooled</strong> One instance of the component per request, with instances
reused from a pool.</li>
                  
  <li>
  <strong>transient</strong> One instance of the component per request, with instances
destroyed on release.</li>
              
  </ul>
          
      
  
  <div id="authors" align="right">by&nbsp;The Avalon Documentation Team</div>
  </div>
  </div>
  </div>
  </td>
  <!--================= end Content ==================-->
  </tr>
  </tbody>
  </table>
  <!--================= end Main ==================-->
  <!--================= start Footer ==================-->
  <div id="footer">
  <table summary="footer" cellspacing="0" cellpadding="4" width="100%" border="0">
  <tbody>
  <tr>
  <!--================= start Copyright ==================-->
  <td colspan="2">
  <div align="center">
  <div class="copyright">
                Copyright &copy; 2003&nbsp;The Apache Software Foundation.. All rights
reserved.
              </div>
  </div>
  </td>
  <!--================= end Copyright ==================-->
  </tr>
  <tr>
  <td align="left">
  <!--================= start Host ==================-->
  <!--================= end Host ==================--></td><td align="right">
  <!--================= start Credits ==================-->
  <div align="right">
  <div class="credit"></div>
  </div>
  <!--================= end Credits ==================-->
  </td>
  </tr>
  </tbody>
  </table>
  </div>
  <!--================= end Footer ==================-->
  </body>
  </html>
  
  
  

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


Mime
View raw message