avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nic...@apache.org
Subject svn commit: rev 20707 - in avalon/trunk/central/site/src/xdocs/central/laboratory/magic: . engine plug-ins plug-ins/artifact plug-ins/clean plug-ins/jar plug-ins/java plug-ins/plugin plug-ins/prepare plug-ins/xdoc plugins
Date Mon, 31 May 2004 19:17:11 GMT
Author: niclas
Date: Mon May 31 12:17:10 2004
New Revision: 20707

Added:
   avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plug-ins/
      - copied from rev 20654, avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plugins/
   avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plug-ins/artifact/
      - copied from rev 20705, avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plugins/artifact/
   avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plug-ins/clean/
      - copied from rev 20705, avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plugins/clean/
   avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plug-ins/index.xml
      - copied unchanged from rev 20705, avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plugins/index.xml
   avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plug-ins/jar/
      - copied from rev 20705, avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plugins/jar/
   avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plug-ins/java/
      - copied from rev 20705, avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plugins/java/
   avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plug-ins/navigation.xml
      - copied unchanged from rev 20705, avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plugins/navigation.xml
   avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plug-ins/plugin/
      - copied from rev 20705, avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plugins/plugin/
   avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plug-ins/prepare/
      - copied from rev 20705, avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plugins/prepare/
   avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plug-ins/xdoc/
      - copied from rev 20705, avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plugins/xdoc/
Removed:
   avalon/trunk/central/site/src/xdocs/central/laboratory/magic/plugins/
Modified:
   avalon/trunk/central/site/src/xdocs/central/laboratory/magic/engine/index.xml
   avalon/trunk/central/site/src/xdocs/central/laboratory/magic/index.xml
   avalon/trunk/central/site/src/xdocs/central/laboratory/magic/navigation.xml
Log:
Changes in Magic's docs for better menu rendering and a new document explaining te Engine.

Modified: avalon/trunk/central/site/src/xdocs/central/laboratory/magic/engine/index.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/laboratory/magic/engine/index.xml	(original)
+++ avalon/trunk/central/site/src/xdocs/central/laboratory/magic/engine/index.xml	Mon May
31 12:17:10 2004
@@ -8,7 +8,437 @@
   <body>
     <section name="The Magic Engine">
       <p>
+        The <em>Magic Engine</em> is very simple and very fast. It basically

+        has 2 purposes;
       </p>
+      <ol>
+        <li>
+          Property Management.
+        </li>
+        <li>
+          Plugin Management.
+        </li>
+      </ol>
+      <subsection name="Project Organization" >
+        <p>
+          Magic acknowledges in its core that projects are never as simple as
+          isolated single artifact builds, that can be tied together with some
+          'other' means (read, multiproject or reactor). But it seems that it
+          is not required to add a lot of "higher project" support, to gain
+          quite a lot of convenience.
+        </p>
+        <p>
+          A <strong><em>Project</em></strong> consists of <em>Project

+          System</em> plus one or many <em>Subproject(s)</em>.
+        </p>
+        <p>
+          The <strong><em>Project System</em></strong> is nothing
more than a
+          central directory shared by all the <em>subprojects</em> for 
+          resources that are needed across all <em>subprojects.</em> Such
+          resources includes project-wide properties, site generation themes,
+          local artifact repository and probably other in the future.
+        </p>
+        <p>
+          The <strong><em>Subproject</em></strong> is contained in
a directory,
+          and you should be able to nest <em>subprojects</em> in 
+          <em>subprojects</em>, without much concerns. A <em>subproject</em>

+          will need at least one file, <code>magic.properties</code>, in its
+          main directory, but there are other files as well. 
+        </p>
+<source name="Minimal magic.properties file." >
+# Name of the Subproject
+project.name = MyProject
+
+# Location of the Project System
+project.system = ../../../../system
+</source>
+        <p>
+          These is the absolute minimum of a subproject 
+          <code>magic.properties</code> file. It declares the name of the 
+          subproject, and where the central system is located relatively to
+          itself. It is fairly important to have relative directories, to
+          simplify collaboration.
+        </p>
+      </subsection>
+      <subsection name="Properties Management" >
+        <p>
+          The <code>magic.properties</code> file is in the standard 
+          <code>java.util.Properties</code> format, but may also contain Ant

+          styled  property variables, for instance;
+        </p>
+<source name="Sample magic.properties file." >
+# All generated files go to output/ instead of the default target/.
+prepare.dest.dir = output/
+
+# Special manifest needed
+jar.manifest = ${prepare.src.dir}/conf/special.MF
+</source>
+        <p>
+          The Ant-styled variables (${prepare.src.dir} above) are not resolved
+          until they are about to be used, i.e. the value assign doesn't happen
+          until some plugin or local
+          build file calls <code>m_Context.getProperty( "jar.manifest" )</code>.
+        </p>
+        <p>
+          Furthermore, it is possible to <em>nest</em> the variables freely;
+        </p>
+<source name="Advanced variable use." >
+my.variant = eagle
+
+my.strategy.eagle = Fly high and look.
+
+my.strategy.owl = Sit still and listen.
+
+my.current.strategy = ${my.strategy.${my.variant}}
+</source>
+        <p>
+          And if the code looks up 
+          <code>m_Context.getProperty( "my.current.strategy" )</code> it will

+          return "Fly high and look.". This enables fairly advanced builds
+          without that much of an effort.
+        </p>
+        <p>
+          The <em>Magic Engine</em> looks for a lot of different properties 
+          files. And it does so in a special sequence, where the later values
+          will override the earlier ones. I.e. the further to the bottom in the
+          table below the higher the priority.
+        </p>
+        <table>
+          <tr>
+            <th>Definition</th>
+            <th>Property File</th>
+            <th>Purpose</th>
+          </tr>
+          <tr>
+            <td>
+              Prime Properties
+            </td>
+            <td>
+              -
+            </td>
+            <td>
+              Before any properties are read from files, a few are computed
+              internally in the <em>Magic Engine</em> and are populated first.
+              These are called the <em><strong>prime properties</strong></em>
+              and should typically not be overridden. You can find the complete
+              list of these properties below.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              Global Properties
+            </td>
+            <td>
+              ${magic.home.dir}/magic.properties
+            </td>
+            <td>
+              These properties are global through all projects being used.
+              They are located with the <em>Magic Engine</em> installation
+              itself and <strong>should not</strong> be modified by the user
+              directly.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              Project System Properties
+            </td>
+            <td>
+              ${project.system}/magic.properties
+            </td>
+            <td>
+              These are <em>project</em> wide properties, which typically 
+              includes site generation themes, directory layouts (unless 
+              default) and similar.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              Subproject Properties
+            </td>
+            <td>
+              ./magic.properties
+            </td>
+            <td>
+              These properties are located in the <em>subproject</em> itself,

+              as seen above. Most importantly these properties contains the
+              <code>project.name</code> and <code>project.system</code>
+              properties, but other <em>subproject</em> level declarations can
+              be made here.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              User Home Properties
+            </td>
+            <td>
+              ${user.home}/.magic.properties
+            </td>
+            <td>
+              These are properties that are unique to a user, and are required
+              in all <em>projects</em>. This includes user names at hosts, 
+              preferred remote repositories, preferred local repository 
+              locations, and similar things.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              User Project Properties
+            </td>
+            <td>
+              ${project.home}/user-magic.properties
+            </td>
+            <td>
+              <em>Project</em> wide properties that a user wants to apply. This
+              file <strong>should not</strong> be committed to any central
+              source code management system (e.g. CVS or Subversion), but be
+              kept as private settings.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              User Subproject Properties
+            </td>
+            <td>
+              ./user-magic.properties
+            </td>
+            <td>
+              <em>Subproject</em> wide properties that a user wants to apply.

+              This file <strong>should not</strong> be committed to any central
+              source code management system (e.g. CVS or Subversion), but be
+              kept as private settings.
+            </td>
+          </tr>
+        </table>
+        <p>
+          This will provide for the flexibility required by most projects and 
+          users.
+        </p>
+        <p>
+          The complete current list of <em>Prime Properties</em>;
+        </p>
+        <table>
+          <tr>
+            <th>Property</th>
+            <th>Description</th>
+          </tr>
+          <tr>
+            <td>
+              user.home
+            </td>
+            <td>
+              A copy of the Java system property <code>user.home</code>. This
+              so that it can be used as a variable in 
+              <code>magic.properties</code> files.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              java.home
+            </td>
+            <td>
+              A copy of the Java system property <code>java.home</code>. This
+              so that it can be used as a variable in 
+              <code>magic.properties</code> files.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              java.version
+            </td>
+            <td>
+              A copy of the Java system property <code>java.version</code>. This
+              so that it can be used as a variable in 
+              <code>magic.properties</code> files.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              magic.home.dir
+            </td>
+            <td>
+              The directory where the Magic Engine is installed.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              magic.plugins.dir
+            </td>
+            <td>
+              The directory where the Magic Plugins are installed.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              magic.repository.dir
+            </td>
+            <td>
+              The directory where Magic will be storing/retrieving downloaded
+              artifacts. This directory is expected to be in Maven layout
+              format, so that it can be reused. It defaults to 
+              <code>${user.home}/.maven/repository</code>.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              magic.project.dir
+            </td>
+            <td>
+              The 'current' subproject's directory as an absolute path.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              magic.temp.dir
+            </td>
+            <td>
+              The Magic temporary directory, where files can be created during
+              the build run, but will be removed on exit.
+            </td>
+          </tr>
+          <tr>
+            <td>
+              magic.year
+            </td>
+            <td>
+              The year Magic was started. (Values: >=2004 )
+            </td>
+          </tr>
+          <tr>
+            <td>
+              magic.month
+            </td>
+            <td>
+              The month Magic was started. (Values: 1-12)
+            </td>
+          </tr>
+          <tr>
+            <td>
+              magic.date
+            </td>
+            <td>
+              The day of the month Magic was started. (Values: 1-31)
+            </td>
+          </tr>
+          <tr>
+            <td>
+              magic.hour
+            </td>
+            <td>
+              The hour of the day Magic was started. (Values: 0-23)
+            </td>
+          </tr>
+          <tr>
+            <td>
+              magic.minute
+            </td>
+            <td>
+              The minute Magic was started. (Values: 0-59)
+            </td>
+          </tr>
+          <tr>
+            <td>
+              magic.second
+            </td>
+            <td>
+              The second Magic was started. Values here are a bit confusing.
+              It seems that seconds could be from 0-60 or even 0-61, due to
+              additions of Leap Seconds every now and then by the time keeping
+              authorities. Don't depend on 0-59.
+            </td>
+          </tr>
+        </table>
+      </subsection>
+      <subsection name="Plugin Management" >
+        <p>
+          The second main task of the <em>Magic Engine</em> is the management
+          of the <em>Plugins</em>.
+        </p>
+        <p>
+          <em><strong>Plugins</strong></em> are the work horses of
Magic. They
+          do all the work to get the job done. Currently, only BeanShell 
+          scripted plugins are supported, but later native Java plugins will
+          also be supported.
+        </p>
+        <p>
+          The <em>Magic Engine</em> Plugin management is centered around a
+          partial Avalon Framework 4 lifecycle model. Plugins can be
+          <code>LogEnabled, Contextualizable, Serviceable</code> and 
+          <code>Initializable.</code>
+        </p>
+        <p>
+          <strong><code>contextualize()</code></strong> will pass
a 
+          <code>PluginContext</code> which contains the properties, and many
+          directories needed by the plugins.
+        </p>
+        <p>
+          <strong><code>service()</code></strong> will pass a 
+          <code>PluginServiceManager</code>, where plugins can lookup other
+          plugins.
+        </p>
+        <p>
+         <strong>Note:</strong> Due to BeanShell's scripted nature
+          it is not possible to use another plugin's Type for a member, since
+          at the time of the compilation of the plugin, the dependent plugin
+          has not yet been created, which typically happens in the lookup() 
+          method. The recommended pattern looks like this;
+        </p>
+<source name="Sample Plugin" >
+public class MyPlugin extends AbstractPlugin
+    implements Serviceable
+{
+    private Object m_PreparePlugin;
+    private Object m_XDocPlugin;
+    
+    public void service( ServiceManager man )
+        throws ServiceException
+    {
+        /* Instantiate the Prepare plugin so the default Prepare properties
+           get read and initiated.
+        */
+        m_PreparePlugin = man.lookup( "prepare" );
+        m_XDocPlugin = man.lookup( "xdoc" );
+    }
+    
+    public void fluff()
+    {
+        /* Notify that "my" is about to start. */
+        notifyPreMethod( "my" );
+        XDocPlugin xdoc = (XDocPlugin) m_XDocPlugin;
+        :
+        :
+        :
+        
+        /* Notify that a step has been completed. */
+        notifyStep( "my", "prepare-generation" );
+        
+        xdoc.generate();
+        
+        /* Notify that "my" has finished. */
+        notifyPostMethod( "my" );
+    }
+}
+</source>
+        <p>
+          In this example, we not only see the required casting of Plugin types,
+          but also the notification system. The <code>AbstractPlugin</code> 
+          class, allows a notification system, where plugins can register 
+          themselves as listeners on the progress of other plugins. There is
+          the "Pre" step, the "Post" step and any arbitrary steps in between
+          given a name.
+        </p>
+        <p>
+          Again it is important to recognize that Plugins are not loaded by 
+          default, so if they are not instantiated they will not register
+          themselves to other plugins. Typically, one would in such case
+          define an <code>init()</code> method, and ensure that the 
+          <code>init()</code> method is called early enough. This is done
+          through the sequencing system.
+        </p>
+        
+        <p>
+          <strong><em>To be continued....</em></strong>
+        </p>
+      </subsection>
     </section>
   </body>
 </document>

Modified: avalon/trunk/central/site/src/xdocs/central/laboratory/magic/index.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/laboratory/magic/index.xml	(original)
+++ avalon/trunk/central/site/src/xdocs/central/laboratory/magic/index.xml	Mon May 31 12:17:10
2004
@@ -129,13 +129,15 @@
             go to tools/magic
           </li>
           <li>
-            run "magic build" .  This will validate and install the plugins.
+            run "magic" .  This will validate and install the plugins.
           </li>
           <li>
-            go to legacy/avalon/framework/api
+            go to tools/magic/test-project and run run "magic java.compile" 
+            or "magic jar.jar"
           </li>
           <li>
-            run "magic java.compile" or "magic jar.jar"
+            or go to central/site and run "magic", which will generate the
+            Avalon site.
           </li>
         </ol>
       </subsection>
@@ -153,19 +155,10 @@
             Unittesting with reporting.
           </li>
           <li>
-            Fix up so that the xdoc plugin works (now missing some jars in classpath).
-          </li>
-          <li>
-            Filtering in source copying.
-          </li>
-          <li>
-            Better handling of Site xdoc aggregation in the xdoc plugin.
-          </li>
-          <li>
             Add xdocs to the existing plugins.
           </li>
           <li>
-            Some simple sequencing mechanism.
+            A more sophisticated sequencing mechanism with groups.
           </li>
           <li>
             Better error handling.

Modified: avalon/trunk/central/site/src/xdocs/central/laboratory/magic/navigation.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/laboratory/magic/navigation.xml	(original)
+++ avalon/trunk/central/site/src/xdocs/central/laboratory/magic/navigation.xml	Mon May 31
12:17:10 2004
@@ -24,7 +24,7 @@
  <body>
     <menu>
       <item name="Engine" href="engine/index.html"/>
-      <item name="Plugins" href="plugins/index.html"/>
+      <item name="Plugins" href="plug-ins/index.html"/>
     </menu>
  </body>
 

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


Mime
View raw message