avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mcconn...@apache.org
Subject cvs commit: avalon-sandbox/merlin/merlin-smp/xdocs/starting/advanced profiles.xml selectors.xml
Date Sat, 05 Apr 2003 11:54:27 GMT
mcconnell    2003/04/05 03:54:27

  Modified:    merlin/merlin-smp project.properties project.xml
               merlin/merlin-smp/xdocs navigation.xml
               merlin/merlin-smp/xdocs/about navigation.xml
               merlin/merlin-smp/xdocs/starting/advanced profiles.xml
                        selectors.xml
  Log:
  Pluggable Profile selection policy tutorial.
  
  Revision  Changes    Path
  1.3       +1 -1      avalon-sandbox/merlin/merlin-smp/project.properties
  
  Index: project.properties
  ===================================================================
  RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/project.properties,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- project.properties	13 Mar 2003 03:52:32 -0000	1.2
  +++ project.properties	5 Apr 2003 11:54:27 -0000	1.3
  @@ -15,7 +15,7 @@
   sun.j2se.link = http://java.sun.com/j2se/1.4/docs/api/
   avalon.framework.link = http://avalon.apache.org/framework/api/
   avalon.logkit.link = http://avalon.apache.org/logkit/api/
  -avalon.lifecycle.link = http://avalon.apache.org/lifecycle/api/
  +avalon.lifecycle.link = http://avalon.apache.org/sandbox/lifecycle/api/
   excalibur.configuration.link = http://avalon.apache.org/excalibur/configuration/api/
   excalibur.pool.link = http://avalon.apache.org/excalibur/pool/api/
   excalibur.thread.link = http://avalon.apache.org/excalibur/thread/api/
  
  
  
  1.6       +1 -1      avalon-sandbox/merlin/merlin-smp/project.xml
  
  Index: project.xml
  ===================================================================
  RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/project.xml,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- project.xml	4 Apr 2003 15:49:44 -0000	1.5
  +++ project.xml	5 Apr 2003 11:54:27 -0000	1.6
  @@ -105,7 +105,7 @@
     </packageGroups>
   
     <reports>
  -    <report>maven-javadoc-plugin</report>
  +    <!--<report>maven-javadoc-plugin</report>-->
       <report>maven-jdepend-plugin</report>
       <report>maven-changelog-plugin</report>
       <report>maven-file-activity-plugin</report>
  
  
  
  1.5       +1 -1      avalon-sandbox/merlin/merlin-smp/xdocs/navigation.xml
  
  Index: navigation.xml
  ===================================================================
  RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/navigation.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- navigation.xml	2 Apr 2003 21:57:58 -0000	1.4
  +++ navigation.xml	5 Apr 2003 11:54:27 -0000	1.5
  @@ -11,7 +11,7 @@
       </links>
   
       <menu name="About Merlin">
  -      <item name="Overview" href="/index.html"/>
  +      <item name="Overview" href="/about/index.html"/>
         <item name="Getting Started" href="/starting/index.html"/>
         <item name="Merlin System" href="/merlin/index.html"/>
         <item name="Meta Model" href="/meta/index.html"/>
  
  
  
  1.3       +1 -1      avalon-sandbox/merlin/merlin-smp/xdocs/about/navigation.xml
  
  Index: navigation.xml
  ===================================================================
  RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/about/navigation.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- navigation.xml	2 Apr 2003 21:57:58 -0000	1.2
  +++ navigation.xml	5 Apr 2003 11:54:27 -0000	1.3
  @@ -10,7 +10,7 @@
       </links>
   
       <menu name="About Merlin">
  -      <item name="Overview" href="/about/index.html">
  +      <item name="Overview" href="/index.html">
           <item name="Purpose" href="/about/purpose.html"/>
           <item name="Features" href="/about/features.html"/>
           <item name="Benefits" href="/about/benefits.html"/>
  
  
  
  1.2       +124 -1    avalon-sandbox/merlin/merlin-smp/xdocs/starting/advanced/profiles.xml
  
  Index: profiles.xml
  ===================================================================
  RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/starting/advanced/profiles.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- profiles.xml	2 Apr 2003 15:52:16 -0000	1.1
  +++ profiles.xml	5 Apr 2003 11:54:27 -0000	1.2
  @@ -10,8 +10,131 @@
     <body>
       <section name="Advanced Features">
         <subsection name="Packaged Deployment Profiles">
  -        <p>In preparation.</p>
  +        <p>
  +          Central to the Merlin component management model is the notion
  +          deployment profiles. A profile is a prefined deployment template. 
  +          It enables Merlin to establish a component type and associated
  +          context, parameterization and/or configuration information as a 
  +          candidate scenario when building a connected set of commponents.
  +        </p>
  +        <p>
  +          Component deployment profiles are co-located with the component
  +          implementation class under a .xprofile resource.
  +        </p>
         </subsection>
  +      <subsection name="Creating a Profile">
  +        <p>
  +          This tutorial extends the interfaces, classes and meta info
  +          declared in the <a href="../hello/dependencies.html">dependencies tutorial</a>

  +          by adding a configurable seed value to the RandomGenerator component. Without
  +          the benefit of a profile, users would be forced to declare a configuration 
  +          under the block.xml directive. By providing one or more profiles, we enable
  +          Merlin to automatically select a deployment scenario candidate and use this
  +          during the assembly phase. 
  +        </p>
  +        <p>
  +          The RandomGeneratorProvider source and the corresponding profile directive
  +          is presented below.
  +        </p>
  +        <p><i>RandomGeneratorProvider.java</i></p>
  +<source>
  +
  +package tutorial;
  +
  +import java.util.Random;
  +
  +import org.apache.avalon.framework.configuration.Configuration;
  +import org.apache.avalon.framework.configuration.ConfigurationException;
  +import org.apache.avalon.framework.configuration.Configurable;
  +import org.apache.avalon.framework.logger.AbstractLogEnabled;
  +
  +/**
  + * An implementation of a random number generator.
  + */
  +public class RandomGeneratorProvider extends AbstractLogEnabled 
  +  implements Configurable, RandomGenerator
  +{
  +
  +    private Random m_random = null;
  +
  +   /**
  +    * Configuration of the component by the container.  The 
  +    * implementation get a child element named 'source' and 
  +    * assigns the value of the element to a local variable.
  +    *
  +    * @param config the component configuration
  +    * @exception ConfigurationException if a configuration error occurs
  +    */
  +    public void configure( Configuration config ) throws ConfigurationException
  +    {
  +        getLogger().info( "configuration stage" );
  +        long seed = config.getChild( "seed" ).getValueAsLong( 0 );
  +        getLogger().info( "seed: " + seed );
  +        m_random = new Random( System.currentTimeMillis() * seed );
  +    }
  +
  +   /**
  +    * Return a random integer
  +    * @return the random number
  +    */
  +    public int getRandom()
  +    {
  +        return m_random.nextInt();
  +    }
  +}
  +</source>
  +        <p>
  +          The RandomGeneratorProvider.xprofile contains the defintion of multiple tagged
  +          deployment scenarios.  During assembly Merlin will attempt to locate an explicit
  +          deployment profile (a compoennt declaration in the block.xml).  In no explicit
  +          profile is available Merlin will select a packaged profile based on the xprofile
  +          declarations, otherwise Merlin will attempt to construct an implict profile.
  +        </p>
  +        <p><i>RandomGeneratorProvider.xprofile</i></p>
  +<source><![CDATA[
  +<?xml version="1.0"?>
  +
  +<profiles>
  +  <profile name="randomizer">
  +    <configuration>
  +      <seed>1024</seed>
  +    </configuration>
  +  </profile>
  +</profiles>
  +]]></source>
  +      </subsection>
  +      <subsection name="Executing the tutorial">
  +        <p>
  +        Build and run the tutorial.
  +        </p>
  +        <source>
  +$ ant
  +$ merlin build\classes
  +        </source>
  +        <p>
  +        In the logging output we see that Merlin has automatically
  +        locating the RandomGeneratorProvider using the packaged profile.
  +        </p>
  +<source>
  +[INFO   ] (tutorial.hello.random-provider#randomizer): configuration stage
  +[INFO   ] (tutorial.hello.random-provider#randomizer): seed: 1024
  +[INFO   ] (tutorial.hello): random: 6608684
  +</source>
  +        <p>
  +        Note: When constructing an name for the component based on a 
  +        packaged profile, Merlin will append the component type name to the 
  +        profile name, seperated by the # character resulting in the 
  +        compoennt name 'random-provider#randomizer'.
  +        </p>
  +
  +      </subsection>
  +      <subsection name="Profile selection">
  +        <p>
  +        The <a href="selectors.html">next tutorial</a> describes the 
  +        mechansims used to influence profile selection within Merlin. 
  +        </p>
  +      </subsection>
  +
       </section>
     </body>
   
  
  
  
  1.2       +167 -2    avalon-sandbox/merlin/merlin-smp/xdocs/starting/advanced/selectors.xml
  
  Index: selectors.xml
  ===================================================================
  RCS file: /home/cvs/avalon-sandbox/merlin/merlin-smp/xdocs/starting/advanced/selectors.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- selectors.xml	2 Apr 2003 15:52:16 -0000	1.1
  +++ selectors.xml	5 Apr 2003 11:54:27 -0000	1.2
  @@ -9,8 +9,173 @@
     </header>
     <body>
       <section name="Advanced Features">
  -      <subsection name="Profile Selectors">
  -        <p>In preparation.</p>
  +      <subsection name="Profile Selection">
  +        <p>
  +          In the <a href="profiles.html">Profile tutorial</a> we covered the

  +          mechanisms used to establish a set of preconfigured deployment 
  +          profiles.  Generally speaking the combination of profile overriding 
  +          in the block.xml &lt;component&gt; directive, packaged profiles, 
  +          and default configurations is sufficient.  However, mechanisms are 
  +          provided for the introduction of profile selection policy.  In this
  +          tutorial we include multiple deployment profiles to the random 
  +          generator component and we define a custom profile selector.  The 
  +          selector is declatred to Merlin as an attribute of the dependency 
  +          declared by the consuming component (HelloComponent). 
  +        </p>
  +        <p>
  +          Component deployment profiles are co-located with the component
  +          implementation class under a .xprofile resource.
  +        </p>
  +      </subsection>
  +      <subsection name="Adding multiple profiles">
  +        <p>
  +          The RandomGeneratorProvider.xprofile is updated to include 
  +          multiple profiles.  
  +        </p>
  +        <p><i>RandomGeneratorProvider.xprofile</i></p>
  +<source><![CDATA[
  +<?xml version="1.0"?>
  +
  +<profiles>
  +
  +  <profile name="primary">
  +    <configuration>
  +      <seed>1024</seed>
  +    </configuration>
  +  </profile>
  +
  +  <profile name="secondary">
  +    <configuration>
  +      <seed>2048</seed>
  +    </configuration>
  +  </profile>
  +
  +</profiles>
  +]]></source>
  +      </subsection>
  +      <subsection name="Creating a ProfileSelector">
  +        <p>
  +          A ProfileSelector may be declared to Merlin as part of a dependency
  +          declaration.  The following code is an implementation of a profile
  +          selector.
  +        </p>
  +        <p><i>RandomProfileSelector.java</i></p>
  +<source><![CDATA[
  +package tutorial;
  +
  +import org.apache.avalon.assembly.engine.profile.ProfileSelector;
  +import org.apache.avalon.framework.logger.AbstractLogEnabled;
  +import org.apache.avalon.meta.info.StageDescriptor;
  +import org.apache.avalon.meta.info.DependencyDescriptor;
  +import org.apache.avalon.meta.model.Profile;
  +
  +/**
  + * Select one profile from the multiple profile provided.
  + */
  +public class RandomProfileSelector extends AbstractLogEnabled
  +    implements ProfileSelector
  +{
  +
  +    /**
  +     * Returns the preferred profile form an available selection of 
  +     * candidate profiles.
  +     * @param profiles the set of candidate profiles
  +     * @param dependency the service dependency
  +     * @return the preferred profile or null if no satisfactory provider can be established
  +     */
  +    public Profile select( Profile[] profiles, DependencyDescriptor dependency )
  +    {
  +        if( profiles.length == 0 )
  +        {
  +            return null;
  +        }
  +
  +        //
  +        // just for fun log the available profiles
  +        //
  +
  +        for( int i=0; i<profiles.length; i++ )
  +        {
  +            Profile profile = profiles[i];
  +            getLogger().info( "available profile: " + profile.getName() );
  +        }
  +
  +        //
  +        // select the profile with the highest seed value
  +        //
  +
  +        long seed = 0;
  +        Profile selection = profiles[0];
  +        for( int i=0; i<profiles.length; i++ )
  +        {
  +            Profile profile = profiles[i];
  +            long value = profile.getConfiguration().getChild( "seed" ).getValueAsLong(
0 );
  +            if( value > seed )
  +            {
  +                seed = value;
  +                selection = profile;
  +            }
  +        }
  +        return selection;
  +    }
  +
  +    /**
  +     * Returns the preferred profile form an available selection of 
  +     * candidate profiles.
  +     * @param profiles the set of candidate profiles
  +     * @param stage the service stage depedency
  +     * @return the prefered profile or null if no satisfactory provider can be established
  +     */
  +    public Profile select( Profile[] profiles, StageDescriptor stage )
  +    {
  +        return null;
  +    }
  +}
  +]]></source>
  +      </subsection>
  +      <subsection name="Associating the selector with a dependency">
  +        <p>
  +          A custom selector is declared under the dependent component. This is 
  +          achieved by declaring the "urn:avalon:profile.selector" attribute
  +          with a value corresponding to the classname of the selector. 
  +        </p>
  +        <p><i>HelloComponent.xinfo</i></p>
  +<source><![CDATA[
  +<type>
  +  <info>
  +    <name>hello</name>
  +    <version>1.0</version>
  +  </info>
  +  <dependencies>
  +    <dependency key="random" type="tutorial.RandomGenerator">
  +      <attributes>
  +        <attribute key="urn:avalon:profile.selector" value="tutorial.RandomProfileSelector"/>
  +      </attributes>
  +    </dependency>
  +  </dependencies>
  +</type>
  +]]></source>
  +      </subsection>
  +      <subsection name="Executing the tutorial">
  +        <p>
  +        Build and run the tutorial.
  +        </p>
  +        <source>
  +$ ant
  +$ merlin build\classes
  +        </source>
  +        <p>
  +        In the logging output we see that Merlin has selected the profile
  +        with the highest seed value (the profile selection criteria implemented
  +        by our custom selector).
  +        </p>
  +<source>
  +[INFO   ] (sys.profiles.selector): available profile: random-provider#primary
  +[INFO   ] (sys.profiles.selector): available profile: random-provider#secondary
  +[INFO   ] (tutorial.hello.random-provider#secondary): configuration stage
  +[INFO   ] (tutorial.hello.random-provider#secondary): seed: 2048
  +[INFO   ] (tutorial.hello): random: -1282354722
  +</source>
         </subsection>
       </section>
     </body>
  
  
  

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


Mime
View raw message