donaldp 02/01/12 19:47:20
Modified: src/java/org/apache/avalon/framework/context Context.java
Log:
Add some more javadocs to try and clarify the role of the context.
Revision Changes Path
1.4 +43 -4
jakarta-avalon/src/java/org/apache/avalon/framework/context/Context.java
Index: Context.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon/src/java/org/apache/avalon/framework/context/Context.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Context.java 11 Dec 2001 09:00:45 -0000 1.3
+++ Context.java 13 Jan 2002 03:47:20 -0000 1.4
@@ -11,17 +11,56 @@
* The context is the interface through which the Component
* and it's Container communicate.
*
- * Each Container-Component relationship will also involve defining
+ * <p>Each Container-Component relationship will also involve defining
* a contract between two entities. This contract will specify the
* services, settings and information that is supplied by the
- * Container to the Component.
+ * Container to the Component.</p>
*
- * This relationship should be documented in a well known place.
+ * <p>This relationship should be documented in a well known place.
* It is sometimes convenient to derive from Context to provide
* a particular style of Context for your Component-Container
* relationship. The documentation for required entries in context
* can then be defined there. (examples include MailetContext,
- * BlockContext etc.)
+ * BlockContext etc.)</p>
+ *
+ * <p>There are traditionally four differet types of Context that may be
+ * used in a system. These ideas are partially derived from linguistic theory
+ * and partially from tradition computer science;</p>
+ *
+ * <ol>
+ * <li>World Context / Per-Application context: This describes application
+ * wide settings/context. An example may be the working directory of the
+ * application.</li>
+ *
+ * <li>Person Context / Per-Component context: This contains context
+ * information specific to the component. An example may be the name of
+ * the component.</li>
+ *
+ * <li>Conversation Context / Per-Session context: This contains context
+ * information specific to the component. An example may be the IP address
+ * of the entity who you are talking to.</li>
+ *
+ * <li>Speach Act Context / Per-Request context: This contains information
+ * about a specific request in component. Example may include the
parameter
+ * submitted to a particular web form or whatever.</li>
+ *
+ * </ol>
+ *
+ * <p>When we implement this (1) and (2) are generally merged into one
interface.
+ * For instance in the Pheonix Application Server there is a BlockContext.
Part
+ * of the BlockContext consists of two methods. One is getHomeDirectory()
and that
+ * belongs to (1) while the other is getName() which belongs to (2).</p>
+ *
+ * <p>(4) is usually passed into a service() style method as parameters.
Often it will
+ * named something like RequestObject. So you may have something like:</p>
+ *
+ * <pre>
+ * void doMagic( int param1, int param2, Context otherParamsInHere );
+ * </pre>
+ *
+ * <p>When (3) is needed in the system it is usually also passed into the a
serice method
+ * method, along with the request context (4). Alternatively it is made
available via the
+ * context representing (4).</p>
*
* @author <a href="mailto:[EMAIL PROTECTED]">Federico Barbieri</a>
* @author <a href="mailto:[EMAIL PROTECTED]">Pierpaolo Fumagalli</a>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
