leosimons 2003/01/05 09:03:03
Modified: fortress/src/java/org/apache/excalibur/fortress
Container.java ContainerConstants.java
ContainerManager.java DefaultContainerManager.java
package.html
fortress/src/java/org/apache/excalibur/fortress/container
AbstractContainer.java DefaultContainer.java
Log:
javadoc, javadoc, and then some more javadoc. More javadoc still to come.
Revision Changes Path
1.21 +32 -5
jakarta-avalon-excalibur/fortress/src/java/org/apache/excalibur/fortress/Container.java
Index: Container.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/fortress/src/java/org/apache/excalibur/fortress/Container.java,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -r1.20 -r1.21
--- Container.java 9 Nov 2002 23:33:56 -0000 1.20
+++ Container.java 5 Jan 2003 17:03:03 -0000 1.21
@@ -52,17 +52,44 @@
import org.apache.avalon.framework.service.ServiceException;
/**
- * The Container is an interface used to assist Container developers to
- * obtain the desired object from the Context. All communication from the
- * ContainerManager to the Container is through the Context object.
+ * The Container is an interface used to mark the Containers in your system.
+ * It is used to functionally identify Containers. It's primary use is to
+ * assist Container developers to obtain the desired object from the Context.
+ * All communication from the ContainerManager to the Container is through the
+ * Context object.
*
- * @author <a href="mailto:[EMAIL PROTECTED]";>Berin Loritsch</a>
+ * @author <a href="mailto:[EMAIL PROTECTED]";>The Avalon Team</a>
* @version CVS $Revision$ $Date$
+ * @see ContainerConstants for the contract surrounding the Container context
+ * @see <a
href="http://jakarta.apache.org/avalon/framework/guide-cop-in-avalon.html";>COP In
Avalon</a>
*/
public interface Container
{
+ /**
+ * This is the method that the ContainerComponentManager and Selector use
+ * to gain access to the ComponentHandlers and ComponentSelectors. The
+ * actual access of the ComponentHandler is delegated to the Container.
+ *
+ * @param role The role we intend to access a Component for.
+ * @param hint The hint that we use as a qualifier
+ * (note: if null, the default implementation is returned).
+ *
+ * @return Object a reference to the ComponentHandler or
+ * ComponentSelector for the role/hint combo.
+ */
Object get( String key, Object hint ) throws ServiceException;
+ /**
+ * This is the method that the ContainerComponentManager and Selector use
+ * to gain access to the ComponentHandlers and ComponentSelectors. The
+ * actual access of the ComponentHandler is delegated to the Container.
+ *
+ * @param role The role we intend to access a Component for.
+ * @param hint The hint that we use as a qualifier
+ * (note: if null, the default implementation is returned).
+ *
+ * @return true if a reference to the role exists.
+ */
boolean has( String key, Object hint );
}
1.13 +13 -1
jakarta-avalon-excalibur/fortress/src/java/org/apache/excalibur/fortress/ContainerConstants.java
Index: ContainerConstants.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/fortress/src/java/org/apache/excalibur/fortress/ContainerConstants.java,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- ContainerConstants.java 10 Nov 2002 11:58:49 -0000 1.12
+++ ContainerConstants.java 5 Jan 2003 17:03:03 -0000 1.13
@@ -59,8 +59,20 @@
*/
public interface ContainerConstants
{
+ /**
+ * Context Directory: The location of the context.
+ */
String CONTEXT_DIRECTORY = "context-root";
+ /**
+ * Work Directory: The location the container can store temperorary files.
+ */
String WORK_DIRECTORY = "container.workDir";
+ /**
+ * Threads per CPU: Information about the hardware the container is running on.
+ */
String THREADS_CPU = "container.threadsPerCPU";
+ /**
+ * Thread timeout: Information about the hardware the container is running on.
+ */
String THREAD_TIMEOUT = "container.threadTimeout";
}
1.48 +20 -6
jakarta-avalon-excalibur/fortress/src/java/org/apache/excalibur/fortress/ContainerManager.java
Index: ContainerManager.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/fortress/src/java/org/apache/excalibur/fortress/ContainerManager.java,v
retrieving revision 1.47
retrieving revision 1.48
diff -u -r1.47 -r1.48
--- ContainerManager.java 10 Nov 2002 16:18:23 -0000 1.47
+++ ContainerManager.java 5 Jan 2003 17:03:03 -0000 1.48
@@ -50,8 +50,21 @@
package org.apache.excalibur.fortress;
/**
- * A ContainerManager is a pocket universe for a container and its
- * components.
+ * The ContainerManager is a single point of contact to manage your Container
+ * resources. It takes care of creating the other managers that a Container
+ * needs to use, as well as initializing the Container. It is designed to be
+ * directly instantiated by whatever class needs to initialize your system.
+ *
+ * <p>
+ * The ContainerManager provides some constants used in the initial
+ * <code>Parameters</code> passed into the ContainerManager. The
+ * ContainerManager uses these values to create all the pieces necessary
+ * for the Container. Below is a table that describes what those options
+ * are.
+ * </p>
+ *
+ * <p>You can think of a ContainerManager is a pocket universe for a container and
its
+ * components.</p>
*
* <p><b>Case 1: Use by a servlet or other "root" entity</b></p>
*
@@ -87,14 +100,15 @@
* </code>
* </pre>
*
- * @author <a href="mailto:[EMAIL PROTECTED]";>Berin Loritsch</a>
+ * @author <a href="mailto:[EMAIL PROTECTED]";>The Avalon Team</a>
* @version CVS $Revision$ $Date$
+ * @see ContainerManagerConstants for the contract surrounding the ContainerManager
context
*/
public interface ContainerManager
{
/**
- * Get a reference to your Container. Typically, you would cast this to
- * whatever interface you will use to interact with it.
+ * Get a reference to the managed Container. This instance is typically cast to
+ * the interface used to interact with the container.
*/
Object getContainer();
}
1.40 +4 -14
jakarta-avalon-excalibur/fortress/src/java/org/apache/excalibur/fortress/DefaultContainerManager.java
Index: DefaultContainerManager.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/fortress/src/java/org/apache/excalibur/fortress/DefaultContainerManager.java,v
retrieving revision 1.39
retrieving revision 1.40
diff -u -r1.39 -r1.40
--- DefaultContainerManager.java 30 Dec 2002 23:15:14 -0000 1.39
+++ DefaultContainerManager.java 5 Jan 2003 17:03:03 -0000 1.40
@@ -70,20 +70,10 @@
import org.apache.excalibur.mpool.PoolManager;
/**
- * The ContainerManager is a single point of contact to manage your Container
- * resources. It takes care of creating the other managers that a Container
- * needs to use, as well as initializing the Container. It is designed to be
- * directly instantiated by whatever class needs to initialize your system.
+ * This is the default implementation of the {@link ContainerManager} interface.
+ * See that interface for a description.
*
- * <p>
- * The ContainerManager provides some constants used in the initial
- * <code>Parameters</code> passed into the ContainerManager. The
- * ContainerManager uses these values to create all the pieces necessary
- * for the Container. Below is a table that describes what those options
- * are.
- * </p>
- *
- * @author <a href="mailto:[EMAIL PROTECTED]";>Berin Loritsch</a>
+ * @author <a href="mailto:[EMAIL PROTECTED]";>The Avalon Team</a>
* @version CVS $Revision$ $Date$
*/
public class DefaultContainerManager
1.2 +1 -1
jakarta-avalon-excalibur/fortress/src/java/org/apache/excalibur/fortress/package.html
Index: package.html
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/fortress/src/java/org/apache/excalibur/fortress/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 11 Dec 2002 03:28:26 -0000 1.1
+++ package.html 5 Jan 2003 17:03:03 -0000 1.2
@@ -2,6 +2,6 @@
<body>
<p>
The <code>fortress</code> package contains an implementation of a component
containment system that follows the ECM semantic concerning component resolution.
-</p>
+See <a href="http://jakarta.apache.org/avalon/excalibur/fortress/";></a> for more
information.</p>
</body>
1.22 +31 -8
jakarta-avalon-excalibur/fortress/src/java/org/apache/excalibur/fortress/container/AbstractContainer.java
Index: AbstractContainer.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/fortress/src/java/org/apache/excalibur/fortress/container/AbstractContainer.java,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -r1.21 -r1.22
--- AbstractContainer.java 24 Nov 2002 16:45:19 -0000 1.21
+++ AbstractContainer.java 5 Jan 2003 17:03:03 -0000 1.22
@@ -87,31 +87,43 @@
import org.apache.excalibur.mpool.PoolManager;
/**
- * The Container is an interface used to mark the Containers in your system.
+ * This abstract implementation provides basic functionality for building
+ * an implementation of the {@link Container} interface.
* It exposes a protected getServiceManager() method so that the
* Container's Manager can expose that to the instantiating class.
*
- * @author <a href="mailto:[EMAIL PROTECTED]";>Berin Loritsch</a>
- * @author <a href="mailto:[EMAIL PROTECTED]";>Peter Royal</a>
- * @author <a href="mailto:[EMAIL PROTECTED]";>Marcus Crafter</a>
- * @author <a href="mailto:peter at apache.org">Peter Donald</a>
+ * @author <a href="mailto:[EMAIL PROTECTED]";>The Avalon Team</a>
* @version CVS $Revision$ $Date$
*/
public abstract class AbstractContainer
extends AbstractLogEnabled
implements Contextualizable, Serviceable, Initializable, Disposable, Container
{
+ /** contains the container's context passed in through contextualize() */
protected Context m_context;
+ /** contains the ServiceManager the container will use, based on the one passed
in through service() */
protected ServiceManager m_serviceManager;
+ /** contains the container's LoggerManager, which is extracted from
m_serviceManager */
protected LoggerManager m_loggerManager;
+ /** contains the container's PoolManager, which is extracted from
m_serviceManager */
protected PoolManager m_poolManager;
+ /** contains the container's Queue, which is extracted from m_serviceManager */
protected Queue m_commandQueue;
+ /** contains the container's root ClassLoader, which is extracted from
m_serviceManager */
protected ClassLoader m_classLoader;
+ /** contains the container's RoleManager, which is extracted from
m_serviceManager */
protected RoleManager m_roleManager;
+ /** contains the container's InstrumentManager, which is extracted from
m_serviceManager */
protected InstrumentManager m_instrumentManager;
+ /** contains the container's LifecycleExtensionManager, which is extracted from
m_serviceManager */
+ protected LifecycleExtensionManager m_extManager;
+ /**
+ * Contains entries mapping roles to hint maps, where the hint map contains
+ * mappings from hints to ComponentHandlers.
+ */
protected Map m_mapper = new StaticBucketMap();
+ /** Contains an entry for each ComponentHandler */
protected List m_components = new ArrayList( 10 );
- protected LifecycleExtensionManager m_extManager;
/**
* Pull the manager items from the context so we can use them to set up
@@ -148,10 +160,14 @@
public void service( final ServiceManager serviceManager )
throws ServiceException
{
+ // get non-optional services
+
m_loggerManager = (LoggerManager)serviceManager.lookup( LoggerManager.ROLE
);
m_poolManager = (PoolManager)serviceManager.lookup( PoolManager.ROLE );
m_instrumentManager = (InstrumentManager)serviceManager.lookup(
InstrumentManager.ROLE );
+ // get optional services, or a default if the service isn't provided
+
if( serviceManager.hasService( LifecycleExtensionManager.ROLE ) )
{
m_extManager =
@@ -201,6 +217,7 @@
}
}
+ // set up our ServiceManager
m_serviceManager = new FortressServiceManager( this, serviceManager );
}
@@ -221,10 +238,12 @@
}
/**
- * Add a Component.
+ * Add a Component into the container. This sets the component up for management
+ * by the container by creating an appropriate {@link ComponentHandler}.
*/
protected void addComponent( final ComponentHandlerMetaData metaData )
{
+ // figure out Role
final String classname = metaData.getClassname();
final RoleEntry roleEntry = m_roleManager.getRoleForClassname( classname );
if( null == roleEntry )
@@ -233,11 +252,15 @@
throw new IllegalArgumentException( message );
}
+ // create a handler for the combo of Role+MetaData
final ComponentHandler handler =
getComponentHandler( roleEntry, metaData );
final String role = roleEntry.getRole();
+ // put the role into our role mapper. If the role doesn't exist
+ // yet, just stuff it in as "default". If it does, we create a
+ // ServiceSelector and put that in as "selector".
if( null != role && null != classname && null != handler )
{
Map hintMap = (StaticBucketMap)m_mapper.get( role );
1.15 +4 -7
jakarta-avalon-excalibur/fortress/src/java/org/apache/excalibur/fortress/container/DefaultContainer.java
Index: DefaultContainer.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/fortress/src/java/org/apache/excalibur/fortress/container/DefaultContainer.java,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- DefaultContainer.java 11 Nov 2002 06:28:52 -0000 1.14
+++ DefaultContainer.java 5 Jan 2003 17:03:03 -0000 1.15
@@ -56,13 +56,10 @@
import org.apache.excalibur.fortress.role.RoleEntry;
/**
- * This is the default container, and it marks the default markup for
- * configurations.
+ * This is the default implementation of {@link
org.apache.excalibur.fortress.Container},
+ * adding configuration markup semantics to the {@link AbstractContainer}.
*
- * @author <a href="mailto:[EMAIL PROTECTED]";>Berin Loritsch</a>
- * @author <a href="mailto:[EMAIL PROTECTED]";>Peter Royal</a>
- * @author <a href="mailto:[EMAIL PROTECTED]";>Marcus Crafter</a>
- * @author <a href="mailto:peter at apache.org">Peter Donald</a>
+ * @author <a href="mailto:[EMAIL PROTECTED]";>The Avalon Team</a>
* @version CVS $Revision$ $Date$
*/
public class DefaultContainer
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
