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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
