avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From leosim...@apache.org
Subject cvs commit: jakarta-avalon-excalibur/scratchpad/avalon-cc/src/java/org/apache/cc ComponentDescriptor.java Container.java ContextKeys.java
Date Fri, 22 Nov 2002 22:40:19 GMT
leosimons    2002/11/22 14:40:19

  Added:       scratchpad/avalon-cc .cvsignore
               scratchpad/avalon-cc/src/java/org/apache/ccri
                        DefaultContainer.java
               scratchpad/avalon-cc/src/java/org/apache/cc
                        ComponentDescriptor.java Container.java
                        ContextKeys.java
  Log:
  Initial commit of some rough ideas about some kind of 'minimal reference container implementation'.
This had actually been sitting in a corner of my disk for some time. Adding it now because
the discussion on this is ramping up again on avalon-dev. This is merely intended as a discussion-starter.
The "cc" stands for Concept container.
  
  Revision  Changes    Path
  1.1                  jakarta-avalon-excalibur/scratchpad/avalon-cc/.cvsignore
  
  Index: .cvsignore
  ===================================================================
  bak
  classes
  build
  doc
  dist
  distributions
  target
  *.jpx
  *.local
  *~
  *.class
  *.library
  
  
  
  1.1                  jakarta-avalon-excalibur/scratchpad/avalon-cc/src/java/org/apache/ccri/DefaultContainer.java
  
  Index: DefaultContainer.java
  ===================================================================
  package org.apache.ccri;
  
  import org.apache.cc.Container;
  import org.apache.cc.ContextKeys;
  import org.apache.cc.ComponentDescriptor;
  import org.apache.avalon.framework.logger.Logger;
  import org.apache.avalon.framework.context.Context;
  import org.apache.avalon.framework.context.ContextException;
  import org.apache.avalon.framework.configuration.Configuration;
  import org.apache.avalon.framework.configuration.ConfigurationException;
  import org.apache.avalon.framework.service.ServiceManager;
  import org.apache.avalon.framework.service.ServiceException;
  
  import java.util.ArrayList;
  
  /**
   * Reference implementation of {@see Container}.
   *
   * DefaultContainer contains complete verification for the avalon lifecyle
   * contracts and for the specific contract surrounding Container. A
   * container embeddor which can embed DefaultContainer without having it throw
   * exceptions should be able to embed any Container implementation without
   * having that implementation throw exceptions.
   *
   * @author <a href="avalon-dev@jakarta.apache.org">Avalon Development Team</a>
   * @version $Revision: 1.1 $
   */
  public class DefaultContainer implements Container
  {
      ////////////////////////////////////////////////////////////////////////////
      // Avalon Lifecycle parameter storage
      ////////////////////////////////////////////////////////////////////////////
      protected Logger m_logger;
      protected Context m_context;
      protected Configuration m_configuration;
      protected ServiceManager m_serviceManager;
  
      ////////////////////////////////////////////////////////////////////////////
      // Avalon Lifecycle tracking variables
      ////////////////////////////////////////////////////////////////////////////
      // keep track of current lifecycle state. Change only if the inheritor has
      // a different lifecyle. Insert a stage in the middle by incrementing all
      // stages that come after it by one
      protected final int INVALIDATED = -100; // if we've thrown an exception, we
                                              // will complain loudly except on
                                              // dispose()
      protected final int INSTANTIATED = 0;
      protected int LOG_ENABLED = 1;
      protected int CONTEXTUALIZED = 2;
      protected int SERVICED = 3;
      protected int CONFIGURED = 4;
      protected int INITIALIZED = 5;
      protected int STARTED = 6;
      protected int SUSPENDED = 7;
      protected int RESUMED = 8;    // m_state will never equal resumed;
                                    // resume() bumps us back to STARTED
      protected int STOPPED = 9;
      protected int DISPOSED = 10;
      protected int m_state = -1;
  
      ////////////////////////////////////////////////////////////////////////////
      // Convenience access to Context entries
      ////////////////////////////////////////////////////////////////////////////
      protected ComponentDescriptor[] m_componentDescriptors;
      /** @todo add entries here */
  
      ////////////////////////////////////////////////////////////////////////////
      // Convenience access to ServiceManager entries
      ////////////////////////////////////////////////////////////////////////////
      /** @todo add entries here */
  
      ////////////////////////////////////////////////////////////////////////////
      // Convenience access to Configuration entries
      ////////////////////////////////////////////////////////////////////////////
      /** @todo add entries here */
  
      ////////////////////////////////////////////////////////////////////////////
      // Constructor
      ////////////////////////////////////////////////////////////////////////////
      public DefaultContainer()
      {
          setState( INSTANTIATED );
      }
  
      ////////////////////////////////////////////////////////////////////////////
      // Avalon Lifecycle methods
      ////////////////////////////////////////////////////////////////////////////
  
      public void enableLogging( Logger logger )
      {
          setState( LOG_ENABLED );
  
          m_logger = logger;
      }
      public void contextualize( Context context ) throws ContextException
      {
          setState( CONTEXTUALIZED );
          verifyContext( context );
  
          m_context = context;
      }
      public void service( ServiceManager serviceManager ) throws ServiceException
      {
          setState( SERVICED );
          verifyServiceManager( serviceManager );
  
          m_serviceManager = serviceManager;
      }
      public void configure( Configuration configuration ) throws ConfigurationException
      {
          setState( CONFIGURED );
          verifyConfiguration( configuration );
  
          m_configuration = configuration;
      }
      public void initialize() throws Exception
      {
          setState( INITIALIZED );
  
          // set up convenience access to context contents
          final ArrayList componentList = (ArrayList)m_context.get(
                  ContextKeys.COMPONENT_DESCRIPTOR_LIST );
          m_componentDescriptors = (ComponentDescriptor[])componentList.toArray( new ComponentDescriptor[0]
);
  
          // set up convenience access to serviceManager contents
          /** @todo set up convenience access to serviceManager contents */
  
          // set up convenience access to configuration contents
          /** @todo set up convenience access to configuration contents */
      }
      public void start() throws Exception
      {
          setState( STARTED );
  
          /**@todo: Implement this org.apache.cc.Container method*/
      }
      public void suspend() throws Exception
      {
          setState( SUSPENDED );
  
          /**@todo: Implement this org.apache.cc.Container method*/
      }
      public void resume() throws Exception
      {
          setState( RESUMED );
  
          /**@todo: Implement this org.apache.cc.Container method*/
      }
      public void stop()
      {
          setState( STOPPED );
  
          /**@todo: Implement this org.apache.cc.Container method*/
      }
      public void dispose()
      {
          setState( DISPOSED );
  
          // be nice to garbage collector (and make sure inheritors don't mess up)
          m_logger = null;
          m_context = null;
          m_configuration = null;
          m_serviceManager = null;
          m_componentDescriptors = null;
  
          /**@todo: add all other properties here*/
      }
  
      ////////////////////////////////////////////////////////////////////////////
      // Avalon Lifecycle verification
      ////////////////////////////////////////////////////////////////////////////
  
      /**
       * Check whether the new proposed lifecycle stage is appropriate given the
       * state we were in before this proposal. If it's not, throw an
       * IllegalStateException, otherwise, set the current stage to the new stage.
       *
       * Override only if the inheritor has additional lifecycle stages.
       *
       * @param state
       */
      protected void setState( int state )
      {
          if( m_state == INVALIDATED ) // error occurred previously
          {
              if( state == DISPOSED )
              {
                  m_state = DISPOSED;
                  return; // we'll accept disposal
              }
  
              // but nothing else!
              throw new IllegalStateException(
                      "There was a lifecycle error previously!" ); /** @todo i18n */
          }
  
          if( m_state == SUSPENDED && state == SUSPENDED )
              return; // can call suspend() any number of times in a row
          if( m_state == SUSPENDED && state == RESUMED )
          {
              m_state = STARTED; // resume() brings us back to the STARTED state
              return;
          }
  
          if( m_state >= state ) // currently there or already been there
          {
              m_state = INVALIDATED; // invalid lifecycle handling
              throw new IllegalStateException( "Was already done" ); /** @todo i18n */
          }
          if( m_state != (state-1) ) // won't accept skipping a stage!
          {
              m_state = INVALIDATED; // invalid lifecycle handling
              throw new IllegalStateException( "Not ready for that yet" ); /** @todo i18n
*/
          }
  
          // everything ok
  
          // set the new state
          m_state = state;
      }
  
      /**
       * Make sure this context contains all the information DefaultContainer
       * needs for operation.
       *
       * Override only if the inheritor has additional context needs.
       *
       * @param context
       * @throws ContextException if the Context is invalid
       */
      protected void verifyContext( Context context )
              throws ContextException
      {
          context.get(ContextKeys.COMPONENT_DESCRIPTOR_LIST);
          /** @todo: verify context contents */
      }
      /**
       * Make sure the ServiceManager contains all the services DefaultContainer
       * needs for operation.
       *
       * Override only if the inheritor has additional dependencies.
       *
       * @param serviceManager
       * @throws ServiceException if the ServiceManager is invalid
       */
      protected void verifyServiceManager( ServiceManager serviceManager )
              throws ServiceException
      {
          /** @todo: verify dependencies are satisfied */
      }
      /**
       * Make sure this configuration contains all the information
       * DefaultContainer needs for operation.
       *
       * Override only if the inheritor has additional configuration needs.
       *
       * @param configuration
       * @throws ConfigurationException if the Configuration is invalid
       */
      protected void verifyConfiguration( Configuration configuration )
              throws ConfigurationException
      {
          /** @todo: verify configuration contents */
      }
  }
  
  
  1.1                  jakarta-avalon-excalibur/scratchpad/avalon-cc/src/java/org/apache/cc/ComponentDescriptor.java
  
  Index: ComponentDescriptor.java
  ===================================================================
  package org.apache.cc;
  
  /** @todo define what a ComponentDescriptor is, or figure out how to define
   *  Container without doing so. */
  public class ComponentDescriptor
  {
  }
  
  
  1.1                  jakarta-avalon-excalibur/scratchpad/avalon-cc/src/java/org/apache/cc/Container.java
  
  Index: Container.java
  ===================================================================
  package org.apache.cc;
  
  import org.apache.avalon.framework.logger.LogEnabled;
  import org.apache.avalon.framework.logger.Logger;
  import org.apache.avalon.framework.context.Contextualizable;
  import org.apache.avalon.framework.context.Context;
  import org.apache.avalon.framework.context.ContextException;
  import org.apache.avalon.framework.configuration.Configurable;
  import org.apache.avalon.framework.configuration.Configuration;
  import org.apache.avalon.framework.configuration.ConfigurationException;
  import org.apache.avalon.framework.service.Serviceable;
  import org.apache.avalon.framework.service.ServiceManager;
  import org.apache.avalon.framework.service.ServiceException;
  import org.apache.avalon.framework.activity.Initializable;
  import org.apache.avalon.framework.activity.Startable;
  import org.apache.avalon.framework.activity.Disposable;
  import org.apache.avalon.framework.activity.Suspendable;
  
  
  /**
   * A passive entity that can host avalon-compliant components.
   *
   * @author <a href="avalon-dev@jakarta.apache.org">Avalon Development Team</a>
   * @version $Revision: 1.1 $
   */
  public interface Container extends LogEnabled, Contextualizable, Serviceable,
          Configurable, Initializable, Startable
  {
      /**
       * The logger the Container should send messages to. Up to implementation
       * whether hosted components inherit this logger.
       */
      void enableLogging( Logger logger );
      /**
       * The context in which the container operates. Up to implementation which
       * parts of this context are inherited.
       * The most important thing in the context is the ComponentProfileMap which
       * contains all the information about the components the container is to
       * host.
       *
       * @param context
       * @throws ContextException
       */
      void contextualize( Context context ) throws ContextException;
      /**
       * Dependencies the container or hosted components have. These are
       * inherited by hosted components olny if the container cannot satisfy the
       * dependency internally.
       *
       * @param serviceManager
       * @throws ServiceException
       */
      void service( ServiceManager serviceManager ) throws ServiceException;
      /**
       * Configuration of the container. Contents are not inherited by hosted
       * components. A special section inside the configuration is defined which
       * serves as a default base configuration for hosted components.
       *
       * @param configuration
       * @throws ConfigurationException
       */
      void configure( Configuration configuration ) throws ConfigurationException;
  
      /**
       * Perform context, dependency and configuration verification and take
       * setup action based on these if neccesary.
       *
       * @throws Exception
       */
      void initialize() throws Exception;
  
      /**
       * Instantiate all hosted components and take them through their lifecycle
       * up to start().
       *
       * @throws Exception
       */
      void start() throws Exception;
  
      /**
       * Suspend all hosted components that can be suspended.
       *
       * @throws Exception
       */
      void suspend() throws Exception;
  
      /**
       * Resume all hosted components that have been suspended.
       *
       * @throws Exception
       */
      void resume() throws Exception;
  
      /**
       * Stop and dispose of all hosted components.
       *
       * @throws Exception
       */
      void stop();
  
      /**
       * Dispose of all acquired resources.
       */
      void dispose();
  }
  
  
  1.1                  jakarta-avalon-excalibur/scratchpad/avalon-cc/src/java/org/apache/cc/ContextKeys.java
  
  Index: ContextKeys.java
  ===================================================================
  package org.apache.cc;
  
  public final class ContextKeys
  {
      public static String COMPONENT_DESCRIPTOR_LIST = "avalon:component-descriptor-list";
  
      private ContextKeys() {}
  }
  
  

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