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-excalibur/event/src/xdocs event-howto.xml mpool-howto.xml menu.xml thread-howto.xml thread.xml
Date Mon, 30 Sep 2002 18:34:44 GMT
bloritsch    2002/09/30 11:34:44

  Modified:    event/src/xdocs menu.xml
  Added:       event/src/xdocs event-howto.xml mpool-howto.xml
  Removed:     event/src/xdocs thread-howto.xml thread.xml
  Log:
  Update the docs with MPool how-to
  
  Revision  Changes    Path
  1.11      +0 -4      jakarta-avalon-excalibur/event/src/xdocs/menu.xml
  
  Index: menu.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-avalon-excalibur/event/src/xdocs/menu.xml,v
  retrieving revision 1.10
  retrieving revision 1.11
  diff -u -r1.10 -r1.11
  --- menu.xml	27 Sep 2002 20:30:44 -0000	1.10
  +++ menu.xml	30 Sep 2002 18:34:43 -0000	1.11
  @@ -14,7 +14,6 @@
         <item href="event.html" name="Event"/>
         <item href="command.html" name="Command"/>
         <item href="mpool.html" name="MPool"/>
  -      <item href="thread.html" name="Thread"/>
         <item href="util.html" name="Util"/>
       </menu>
   
  @@ -23,10 +22,7 @@
         <item href="event-howto.html" name="Use Event Queues"/>
   -->
         <item href="command-howto.html" name="Use the Command Manager"/>
  -<!--
         <item href="mpool-howto.html" name="Use MPool"/>
  -        -->
  -      <item href="thread-howto.html" name="Use Thread Pools"/>
         <item href="util-howto.html" name="Use System Util"/>
         <item href="cpuparser-howto.html" name="Extend System Util"/>
       </menu>
  
  
  
  1.1                  jakarta-avalon-excalibur/event/src/xdocs/event-howto.xml
  
  Index: event-howto.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Excalibur Event - Overview</title>
      <authors>
        <person name="Berin Loritsch" email="bloritsch@apache.org"/>
      </authors>
    </header>
    <body>
      <s1 title="Introduction">
        <p>
          This is the Excalibur Event package which includes event queues,
          asynchronous command processing, and the interfaces to support
          event based programming.  Event is heavily influenced by Matt
          Welsh's work with the
          <fork href="http://www.cs.berkeley.edu/~mdw/proj/seda/">SEDA architecture</fork>.
          We forked the portion of his SandStorm server that had to do with
          event processing.  From there we cleaned up the API and made it as
          generic as we could.
        </p>
        <p>
          The Event package actually has five related sub packages inside
          of it.  Event is the basic interfaces for the Queues, Sinks,
          Sources, etc.  Command houses code for the CommandManager so that
          your code can safely process Commands (a type of event) in the
          background.  MPool, short for Managed Pool, houses code for a
          pool implementation that manages its size asynchronously so you
          don't have to worry about it.  Thread is the thread pool code
          which uses MPool to keep track of the threads.  Lastly, Util
          provides some basic utilities so that we can programatically
          determine the number of processors your hardware has.
        </p>
      </s1>
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/09/30 18:34:43 $
      </legal>
    </footer>
  </document>
  
  
  
  1.1                  jakarta-avalon-excalibur/event/src/xdocs/mpool-howto.xml
  
  Index: mpool-howto.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Excalibur Event - How To Use MPool</title>
      <authors>
        <person name="Berin Loritsch" email="bloritsch@apache.org"/>
      </authors>
    </header>
    <body>
      <s1 title="Setting Up the PoolManager">
        <p>
          In order to set up a CommandManager.  For those instructions,
          follow <link href="command-howto.html">the Command "How To"</link>.
          From there, you want to set up the PoolManager using the following
          code:
        </p>
        <source>
          <![CDATA[
  // Using the CommandManager in the variable "commandManager"
  
  PoolManager poolManager = new DefaultPoolManager( commandManager );
          ]]>
        </source>
      </s1>
      <s1 title="Creating Your Pool">
        <p>
          The PoolManager is responsible for manufacturing managed pools,
          and for managing their sizes.  All PoolManager managed pools are
          "soft" limiting.  They will continue to grow while they are being
          accessed heavily, but it will shrink during times of inactivity.
          To create your pool, use the following code:
        </p>
        <source>
          <![CDATA[
  int initialEntries = 20;
  ObjectFactory objectFactory = new MySpecialObjectFactory();
  
  Pool managedPool = poolManager.getManagedPool( objectFactory, initialEntries );
          ]]>
        </source>
        <s2 title="Writing an ObjectFactory">
          <p>
            Writing an Object Factory is not that difficult.  You just need to
            implement the ObjectFactory interface.  Below is an example
            implementation:
          </p>
            <source>
              <![CDATA[
  public class MySpecialObjectFactory implements ObjectFactory
  {
      private final Class m_mySpecialClass;
  
      /** Create default object type */
      public MySpecialObjectFactory()
      {
          this( MySpecialObject.class );
      }
  
      /** Create generic object type */
      public MySpecialObjectFactory( Class specialClass )
      {
          if ( null == specialClass )
          {
              throw new IllegalArgumentException ("Class cannot be null");
          }
  
          m_mySpecialClass = specialClass;
      }
  
      /** Implement the getCreatedClass() method */
      public Class getCreatedClass()
      {
          return m_mySpecialClass;
      }
  
      /** Create an instance */
      public Object newInstance()
          throws Exception
      {
          return getCreatedClass().newInstance();
      }
  
      /** Dispose of an instance */
      public void dispose( Object obj )
      {
          // perform permanent cleanup code
      }
  }
              ]]>
            </source>
        </s2>
        <s2 title="Unmanaged Pools">
          <p>
            There are two unmanaged pool types in MPool:
            FixedSizePool and BlockingFixedSizePool.  They are
            similar to one another, but differ in how they respond
            to insufficient resources.  The FixedSizePool fails fast,
            and throws an exception.  The BlockingFixedSizePool tries
            to wait for a specified number of milliseconds.
          </p>
          <p>
            The Fixed Size Pools are not managed because they will only
            have a certain number of pooled objects at any time.  They
            will never grow or shrink.  They are useful for instances
            where the number of elements are known in advanced.  One
            example is a JDBC connection pool because some vendors require
            you to pay per connection licensing fees.
          </p>
        </s2>
      </s1>
      <s1 title="Using the Pool">
        <p>
          Using the pools are quite simple:
        </p>
        <source>
          <![CDATA[
  Object pooledResource = managedPool.acquire();
  
  // do whatever I want with the pooled resource
  
  managedPool.release( pooledResource );
          ]]>
        </source>
        <p>
          What if we have an object that needs to perform some simple
          clieanup?  Have your Object implement the <code>Resettable</code>
          interface.  What if we are migrating from the old Pool package?
          you don't have to do anything.  MPool knows about the old Pool
          package, and will check for its recyclable method.  It will only
          call the Resettable.reset() method if your object implements both
          interfaces.  Both of these will work:
        </p>
        <source>
          <![CDATA[
  import org.apache.excalibur.mpool.Resettable;
  
  public class ResettableObject implements Resettable
  {
      // All the methods and stuff for the real object...
  
      public void reset()
      {
          // perform small cleanup code...
      }
  }
          ]]>
        </source>
        <source>
          <![CDATA[
  import org.apache.avalon.excalibur.pool.Recyclable;
  
  public class ResettableObject implements Recyclable
  {
      // All the methods and stuff for the real object...
  
      public void recycle()
      {
          // perform small cleanup code...
      }
  }
          ]]>
        </source>
      </s1>
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2002/09/30 18:34:43 $
      </legal>
    </footer>
  </document>
  
  
  

--
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