avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From blorit...@apache.org
Subject cvs commit: jakarta-avalon/src/documentation/xdocs/developing implementing.xml
Date Tue, 30 Oct 2001 14:25:22 GMT
bloritsch    01/10/30 06:25:22

  Modified:    src/documentation/xdocs/developing implementing.xml
  Log:
  reformat code examples, and fix some wording.
  
  Revision  Changes    Path
  1.6       +147 -72   jakarta-avalon/src/documentation/xdocs/developing/implementing.xml
  
  Index: implementing.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon/src/documentation/xdocs/developing/implementing.xml,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- implementing.xml	2001/10/30 14:01:18	1.5
  +++ implementing.xml	2001/10/30 14:25:22	1.6
  @@ -75,7 +75,7 @@
           Initializable and Disposable interfaces.  Since specific information
           about our environment may change, or may need to be customized, we need
           to make our DocumentRepository Configurable.  Our Component makes use
  -        of other Components, and they method that Avalon provides to get
  +        of other Components, and the method that Avalon provides to get
           instances of the required Component is by using a ComponentManager.  We
           will need to implement the Composable interface to get an instance of
           the ComponentManager.
  @@ -95,8 +95,8 @@
   public class DatabaseDocumentRepository
   extends AbstractLoggable
   implements DocumentRepository , Configurable, Composable, Initializable,
  -           Disposable, Component, ThreadSafe {
  -
  +           Disposable, Component, ThreadSafe
  +{
       private boolean initialized = false;
       private boolean disposed = false;
       private ComponentManager manager = null;
  @@ -114,14 +114,16 @@
        * only calling Configure once.
        */
       public final void configure(Configuration conf)
  -    throws ConfigurationException {
  -        if (initialized || disposed) {
  -        
  +        throws ConfigurationException
  +    {
  +        if (initialized || disposed)
  +        {
               throw new IllegalStateException ("Illegal call");
           }
   
  -        if (null == this.dbResource) {
  -                    this.dbResource = conf.getChild("dbpool").getValue();
  +        if (null == this.dbResource)
  +        {
  +            this.dbResource = conf.getChild("dbpool").getValue();
               getLogger().debug("Using database pool: " + this.dbResource);
               // Notice the getLogger()?  This is from AbstractLoggable
               // which I extend for just about all my components.
  @@ -134,32 +136,51 @@
        * the policy of proper lifecycle management.
        */
       public final void compose(ComponentManager cmanager)
  -    throws ComponentException {
  -        if (initialized || disposed) {
  +        throws ComponentException
  +    {
  +        if (initialized || disposed)
  +        {
               throw new IllegalStateException ("Illegal call");
           }
   
  -        if (null == this.manager) {
  +        if (null == this.manager)
  +        {
               this.manager = cmanager;
           }
       }
   
  -    public final void initialize() throws Exception {
  -             if (null == this.manager) throw new IllegalStateException("Not Composed");
  +    public final void initialize()
  +        throws Exception
  +    {
  +        if (null == this.manager)
  +        {
  +            throw new IllegalStateException("Not Composed");
  +        }
  +
           if (null == this.dbResource)
  -                     throw new IllegalStateException("Not Configured");
  +        {
  +            throw new IllegalStateException("Not Configured");
  +        }
   
  -                 if (disposed) throw new IllegalStateException("Already disposed");
  +        if (disposed)
  +        {
  +            throw new IllegalStateException("Already disposed");
  +        }
   
           this.initialized = true;
       }
   
  -    public final void dispose() {
  +    public final void dispose()
  +    {
           this.disposed = true;
  +        this.manager = null;
  +        this.dbresource = null;
       }
   
  -    public final Document getDocument(Principal requestor, int refId) {
  -        if (!initialized || disposed) {
  +    public final Document getDocument(Principal requestor, int refId)
  +    {
  +        if (!initialized || disposed)
  +        {
               throw new IllegalStateException("Illegal call");
           }
   
  @@ -221,12 +242,15 @@
           </para>
           <programlisting>
   <![CDATA[
  -class ContainerComponent implements Component, Initializable, Disposable {
  +class ContainerComponent implements Component, Initializable, Disposable
  +{
       DocumentRepository docs = new DatabaseDocumentRepository();
       GuardianComponent guard = new DocumentGuardianComponent();
       DefaultComponentManager manager = new DefaultComponentManager();
   
  -    public void initialize() throws Exception {
  +    public void initialize()
  +        throws Exception
  +    {
           this.docs.setLogger(Heirarchy.getLoggerFor("document.repository"));
   
           DefaultConfiguration pool = new DefaultConfiguration("dbpool");
  @@ -245,7 +269,8 @@
           this.docs.initialize();
       }
   
  -    public void dispose() {
  +    public void dispose()
  +    {
           this.docs.dispose();
           this.guard.dispose();
       }
  @@ -259,8 +284,8 @@
             life of a Component, you will see bugs.  This also requires intimate
             knowledge of the Components you are instantiating.  An alternate
             approach would be to add a couple methods to the above
  -          ContainerComponent that handles the initialization of the components
  -          dynamically.
  +          <classname>ContainerComponent</classname> that handles the
  +          initialization of the components dynamically.
           </para>
         </section>
         <section>
  @@ -340,7 +365,7 @@
                 </listitem>
                 <listitem>
                   <para>
  -                        Creation and initialization is done when ComponentHandler is
  +                  Creation and initialization is done when ComponentHandler is
                     created.
                   </para>
                 </listitem>
  @@ -362,7 +387,7 @@
                 </listitem>
                 <listitem>
                   <para>
  -                        Creation and initialization is done when ComponentHandler is
  +                  Creation and initialization is done when ComponentHandler is
                     created.
                   </para>
                 </listitem>
  @@ -382,12 +407,15 @@
           </para>
           <programlisting>
   <![CDATA[
  -class ContainerComponent implements Component, Initializable, Disposable {
  +class ContainerComponent implements Component, Initializable, Disposable
  +{
       ComponentHandler docs = null;
       ComponentHandler guard = null;
       DefaultComponentManager manager = new DefaultComponentManager();
   
  -    public void initialize() throws Exception {
  +    public void initialize()
  +        throws Exception
  +    {
           DefaultConfiguration pool = new DefaultConfiguration("dbpool");
           pool.setValue("main-pool");
           DefaultConfiguration conf = new DefaultConfiguration("");
  @@ -411,7 +439,8 @@
           this.docs.initialize();
       }
   
  -    public void dispose() {
  +    public void dispose()
  +    {
           this.docs.dispose();
           this.guard.dispose();
       }
  @@ -487,7 +516,7 @@
           <para>
             This does simplify all the code we had for hand-building the
             Configuration element earlier, and it limits the amount of
  -          information we need to implicitly know right away.  We will take one
  +          information we need to explicitly know right away.  We will take one
             last look at our Container class and see if we really have some
             savings.  Keep in mind that we have five components specified (a
             ComponentSelector counts as a Component), and configurations for
  @@ -498,18 +527,21 @@
   class ContainerComponent implements Component, Initializable, Disposable {
       ExcaliburComponentManager manager = new ExcaliburComponentManager();
   
  -    public void initialize() throws Exception {
  -        DefaultConfigurationBuilder builder =
  -            new DefaultConfigurationBuilder();
  +    public void initialize()
  +        throws Exception
  +    {
  +        DefaultConfigurationBuilder builder = new DefaultConfigurationBuilder();
           Configuration sysConfig = builder.buildFromFile("./conf/system.xconf");
   
  -        this.manager.setLogger(Hierarchy.getDefaultHierarchy().getLoggerFor("document"));
  +        this.manager.setLogger(Hierarchy.getDefaultHierarchy()
  +                               .getLoggerFor("document"));
           this.manager.contextualize(new DefaultContext());
           this.manager.configure(sysConfig);
           this.manager.initialize();
       }
   
  -    public void dispose() {
  +    public void dispose()
  +    {
           this.manager.dispose();
       }
   }
  @@ -547,7 +579,8 @@
             </para>
             <programlisting>
   <![CDATA[
  -interface RoleManager {
  +interface RoleManager
  +{
       String getRoleForName( String shorthandName );
       String getDefaultClassNameForRole( String role );
       String getDefaultClassNameForHint( String hint, String shorthand );
  @@ -577,8 +610,8 @@
   <role-list>
     <role
       name="org.apache.avalon.excalibur.datasource.DataSourceComponentSelector"
  -    shorthand="datasources" default-class=
  -    "org.apache.avalon.excalibur.component.ExcaliburComponentSelector">
  +    shorthand="datasources"
  +    default-class="org.apache.avalon.excalibur.component.ExcaliburComponentSelector">
        <hint shorthand="jdbc"
          class="org.apache.avalon.excalibur.datasource.JdbcDataSourceComponent"/>
        <hint shorthand="j2ee"
  @@ -586,12 +619,12 @@
     </role>
     <role
       name="org.apache.bizserver.docs.DocumentRepository"
  -    shorthand="repository" default-class=
  -    "org.apache.bizserver.docs.DatabaseDocumentRepository"/>
  +    shorthand="repository"
  +    default-class="org.apache.bizserver.docs.DatabaseDocumentRepository"/>
     <role
       name="org.apache.bizserver.docs.GuardianComponent"
  -    shorthand="guardian" default-class=
  -    "org.apache.bizserver.docs.DocumentGuardianComponent"/>
  +    shorthand="guardian"
  +    default-class="org.apache.bizserver.docs.DocumentGuardianComponent"/>
   </role-list>
   ]]>
             </programlisting>
  @@ -607,8 +640,7 @@
             </para>
             <programlisting>
   <![CDATA[
  -DefaultConfigurationBuilder builder =
  -            new DefaultConfigurationBuilder();
  +DefaultConfigurationBuilder builder = new DefaultConfigurationBuilder();
   Configuration sysConfig = builder.buildFromFile("./conf/system.xconf");
   Configuration roleConfig = builder.build(
               this.getClass().getClassLoader()
  @@ -618,7 +650,8 @@
   roles.setLogger(Hierarchy.getDefaultHierarchy().getLoggerFor("document.roles"));
   roles.configure(roleConfig);
   
  -this.manager.setLogger(Hierarchy.getDefaultHierarchy().getLoggerFor("document"));
  +this.manager.setLogger(Hierarchy.getDefaultHierarchy()
  +                       .getLoggerFor("document"));
   this.manager.contextualize(new DefaultContext());
   this.manager.setRoleManager(roles);
   this.manager.configure(sysConfig);
  @@ -685,9 +718,9 @@
           The Component management infrastructure requires that you release any
           Component for which you have obtained a reference.  The reason for this
           restriction is so that the Component's resources can be properly
  -        managed.  A ComponentManager is designed for instances when you have
  +        managed.  A ComponentManager is designed for cases when you have
           multiple types of Components with distinct roles.  A ComponentSelector
  -        is designed for instances when you have multiple types of Components
  +        is designed for cases when you have multiple types of Components
           with the same role.  Another unique aspect of the ComponentSelector is
           that it is a Component by design.  This enables us to get a
           ComponentSelector from a ComponentManager.
  @@ -703,7 +736,8 @@
           <title>Initialization and Disposal Approach</title>
           <programlisting>
   <![CDATA[
  -class MyClass implements Component, Composable, Disposable {
  +class MyClass implements Component, Composable, Disposable
  +{
       ComponentManager manager;
       Guardian myGuard;
   
  @@ -712,8 +746,10 @@
        * the ComponentManager.
        */
       public void compose(ComponentManager manager)
  -    throws ComponentException {
  -        if (this.manager == null) {
  +        throws ComponentException
  +    {
  +        if (this.manager == null)
  +        {
               this.manager = manager;
               myGuard = (Guardian) this.manager.lookup(Guardian.ROLE);
           }
  @@ -722,14 +758,17 @@
       /**
        * This is the method that uses the Guardian.
        */
  -    public void myMethod() throws SecurityException {
  +    public void myMethod()
  +        throws SecurityException
  +    {
           this.myGuard.checkPermission(new BasicPermission("test"));
       }
   
       /**
        * Get rid of our references
        */
  -    public void dispose() {
  +    public void dispose()
  +    {
           this.manager.release(this.myGuard);
           this.myGuard = null;
           this.manager = null;
  @@ -775,7 +814,8 @@
           <title>Exception Handling Approach</title>
           <programlisting>
   <![CDATA[
  -class MyClass implements Composable, Disposable {
  +class MyClass implements Composable, Disposable
  +{
       ComponentManager manager;
   
       /**
  @@ -783,8 +823,10 @@
        * the ComponentManager.
        */
       public void compose(ComponentManager manager)
  -    throws ComponentException {
  -        if (this.manager == null) {
  +        throws ComponentException
  +    {
  +        if (this.manager == null)
  +        {
               this.manager = manager;
           }
       }
  @@ -792,17 +834,27 @@
       /**
        * This is the method that gets the Guardian.
        */
  -    public void myMethod() throws SecurityException {
  +    public void myMethod()
  +        throws SecurityException
  +    {
           Guardian myGuard = null;
  -        try {
  +        try
  +        {
               myGuard = (Guardian) this.manager.lookup(Guardian.ROLE);
               this.criticalSection(myGuard);
  -        } catch (ComponentException ce) {
  +        }
  +        catch (ComponentException ce)
  +        {
               throw new SecurityException(ce.getMessage());
  -        } catch (SecurityException se) {
  +        }
  +        catch (SecurityException se)
  +        {
               throw se;
  -        } finally {
  -            if (myGuard != null) {
  +        }
  +        finally
  +        {
  +            if (myGuard != null)
  +            {
                   this.manager.release(myGuard);
               }
           }
  @@ -811,7 +863,9 @@
       /**
        * Perform critical part of code.
        */
  -    public void criticalSection(Guardian myGuard) throws SecurityException {
  +    public void criticalSection(Guardian myGuard)
  +        throws SecurityException
  +    {
           myGuard.checkPermission(new BasicPermission("test"));
       }
   }
  @@ -846,7 +900,7 @@
             understand a subtle nuance.  The Exception Handling Approach does not
             fail on initialization if the Component is missing from the manager.
             As mentioned before, this is not entirely bad.  Many times, you want
  -          an object to exist, but it is not a failure if a required Component
  +          an object to exist, but it is not a failure if a desired Component
             is missing.
           </para>
         </section>
  @@ -885,25 +939,34 @@
         </para>
         <programlisting>
   <![CDATA[
  -public void myMethod() throws Exception {
  +public void myMethod()
  +    throws Exception
  +{
       ComponentSelector dbSelector = null;
       DataSourceComponent datasource = null;
  -    try {
  +    try
  +    {
           dbSelector = (ComponentSelector)
                   this.manager.lookup(DataSourceComponent.ROLE + "Selector");
           datasource = (DataSourceComponent)
                   dbSelector.select(this.useDb);
   
           this.process(datasource.getConnection());
  -    } catch (Exception e) {
  +    }
  +    catch (Exception e)
  +    {
           throw e;
  -    } finally {
  -        if (datasource != null) {
  +    }
  +    finally
  +    {
  +        if (datasource != null)
  +        {
               dbSelector.release(datasource);
           }
   
  -        if (dbSelector != null) {
  -            this.manager.release(dbSelector);
  +        if (dbSelector != null)
  +        {
  +            this.manager.release(instancesdbSelector);
           }
       }
   }
  @@ -926,15 +989,15 @@
       </section>
     </section>
     <section>
  -    <title>Excalibur's Utitities</title>
  +    <title>Excalibur's Utilities</title>
       <para>
         This last section is included to give you an idea of the types of
         Components and utilities that are included with Apache Avalon Excalibur.
         These utilities are robust, and fully usable in production systems.  We
         do have an unofficial staging project called "Scratchpad" where we iron
         out implementation details for potential new utilities.  Scratchpad
  -      utilities are of varying quality, and their use is not
  -      guaranteed&mdash;although you may have good experience with them.
  +      utilities are of varying quality, and their use is not guaranteed to
  +      remain the same&mdash;although you may have good experience with them.
       </para>
       <section>
         <title>Command Line Interface (CLI)</title>
  @@ -971,6 +1034,18 @@
           pool of Components and reuse instances.  Most of the time this works
           great.  For those last remaining times where a Component cannot be
           reused, use the <classname>SingleThreaded</classname> interface.
  +      </para>
  +    </section>
  +    <section>
  +      <title>LogKit Management</title>
  +      <para>
  +        The Avalon development team realized that many people wanted a simple
  +        mechanism to build complex Logging target heirarchies.  In the same
  +        spirit as the <classname>RoleManager</classname> the team developed
  +        a <classname>LogKitManager</classname> that can be given to the
  +        Excalibur Component Management system meantioned above.  Based on the
  +        "logger" attribute it will give the proper <classname>Logger</classname>
  +        object to the different Components.
         </para>
       </section>
       <section>
  
  
  

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


Mime
View raw message