Author: steveh
Date: Mon Apr 25 15:21:27 2005
New Revision: 164671
URL: http://svn.apache.org/viewcvs?rev=164671&view=rev
Log:
Grammar edits provided by Liza Ketchum.
Modified:
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsContainment.xml
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/development/dev_mode.xml
Modified:
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsContainment.xml
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsContainment.xml?rev=164671&r1=164670&r2=164671&view=diff
==============================================================================
---
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsContainment.xml
(original)
+++
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/controls/controlsContainment.xml
Mon Apr 25 15:21:27 2005
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN"
"http://forrest.apache.org/dtd/document-v13.dtd";>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
"http://forrest.apache.org/dtd/document-v20.dtd";>
<document>
<header>
<title>Controls Containment</title>
@@ -9,7 +9,9 @@
<section><title>Overview</title>
- <p>This document describes the basic architecture for how Beehive Controls
interact with the runtime container they are executing within. Examples of
runtime containers for Controls include:
+ <p>This document describes the basic architecture for how Beehive Controls
interact with the
+ runtime container they are executing within. Examples of
runtime containers for Controls
+ include:
</p>
<ul>
@@ -21,7 +23,7 @@
<li>...</li>
</ul>
- <p>The base runtime comes with a sample container integration for the
servlet container, but the container integration model is flexible enought to
support any and all of the above containers, as well as enabling the list above
to be extended or customized in new and interesting ways. The model makes it
possible to author controls that run in a wide variety of containers, as well
as ones that expect and leverage the capabilities of a specific container
(where desirable).
+ <p>The base runtime comes with a sample container integration for the
servlet container, but the container integration model is flexible enough to
support any and all of the above containers, as well as enabling the list above
to be extended or customized in new and interesting ways. The model makes it
possible to author controls that run in a wide variety of containers, as well
as ones that expect and leverage the capabilities of a specific container
(where desirable).
</p>
<p>This is possible because there is a basic architecture for how Controls
will interact with their container. This includes the interfaces for how a
new type of container can be constructed, or for how an existing runtime
environment can be extended to act as a container of controls.
@@ -39,13 +41,13 @@
<section><title>Basic Architecture</title>
- <p>This section outlines the basic implementation architecture for Control
containment. Containment is based upon an existing JavaBean standard for bean
composition and services, and build atops this to provide additional features
that are unique to Controls.
+ <p>This section outlines the basic implementation architecture for Control
containment. Containment is based upon an existing JavaBean standard for bean
composition and services, and build atop this to provide additional features
that are unique to Controls.
</p>
<section>
<title>The Foundation: JavaBeans Containment</title>
- <p>The basic foundation of Control Containment is the <link
href="http://java.sun.com/products/javabeans/glasgow/beancontext.pdf";>Extensible
Runtime Containment and Services Protocol For JavaBeans"</link>, a little
known but useful containment model for JavaBeans that has been part of J2SE
since 1.2. The intent of the protocol (actually, a set of interfaces and
supporting implementation classes) was to add a simple containment model for
JavaBeans, as well as a mechanism for allowing beans to discover, request, and
use services provided by their container. All of the APIs defined by the
protocol live in the <link
href="http://java.sun.com/j2se/1.5.0/docs/api/java/beans/beancontext/package-summary.html";>java.beans.beancontext</link>
package.
+ <p>The basic foundation of Control Containment is the <a
href="http://java.sun.com/products/javabeans/glasgow/beancontext.pdf";>Extensible
Runtime Containment and Services Protocol For JavaBeans"</a>, a little known
but useful containment model for JavaBeans that has been part of J2SE since
1.2. The intent of the protocol (actually, a set of interfaces and supporting
implementation classes) was to add a simple containment model for JavaBeans, as
well as a mechanism for allowing beans to discover, request, and use services
provided by their container. All of the APIs defined by the protocol live in
the <a
href="http://java.sun.com/j2se/1.5.0/docs/api/java/beans/beancontext/package-summary.html";>java.beans.beancontext</a>
package.
</p>
<p>This diagram shows the basic architecture for this protocol: </p>
@@ -58,7 +60,7 @@
</p>
<ul>
- <li>A JavaBean can be nested within a BeanContext, that acts as a
container for one (or more) beans.</li>
+ <li>A JavaBean can be nested within a BeanContext that acts as a
container for one (or more) beans.</li>
<li>A BeanContext can itself be nested within another BeanContext,
enabling hierarchical composition.</li>
<li>A BeanContext can provide the JavaBean with access to services.
These services may be directly implemented by the BeanContext, or the
BeanContext may simply act as a discovery mechanism/bridge to services provided
by the runtime environment of the BeanContext.</li>
</ul>
@@ -68,7 +70,7 @@
<section><title>BeanContext</title>
- <p>The <link
href="http://java.sun.com/j2se/1.5.0/docs/api/java/beans/beancontext/BeanContext.html";>java.beans.beancontext.BeanContext</link>
interface defines the basic interface for a container of JavaBeans. It
derives from the <link
href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collection.html";>java.util.Collection</link>
interface, so the standard Collection APIs can be used to add, remove, and
iterate over the JavaBeans contained within the context. It also extends the
<link
href="http://java.sun.com/j2se/1.5.0/docs/api/java/beans/beancontext/BeanContextChild.html";>java.beans.beancontext.BeanContextChild</link>
interface (see next section), meaning it is possible for one BeanContext to be
nested within another BeanContext, forming a hierarchical structure.
+ <p>The <a
href="http://java.sun.com/j2se/1.5.0/docs/api/java/beans/beancontext/BeanContext.html";>java.beans.beancontext.BeanContext</a>
interface defines the basic interface for a container of JavaBeans. It
derives from the <a
href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/Collection.html";>java.util.Collection</a>
interface, so the standard Collection APIs can be used to add, remove, and
iterate over the JavaBeans contained within the context. It also extends the
<a
href="http://java.sun.com/j2se/1.5.0/docs/api/java/beans/beancontext/BeanContextChild.html";>java.beans.beancontext.BeanContextChild</a>
interface (see next section), meaning it is possible for one BeanContext to be
nested within another BeanContext, forming a hierarchical structure.
</p>
<p> Whenever you see word "<em>BeanContext</em>" throughout this
document or in API names, mentally replace it with "<em>JavaBeans
Container</em>".
@@ -78,14 +80,14 @@
<section><title>BeanContextChild</title>
- <p>The <link
href="http://java.sun.com/j2se/1.5.0/docs/api/java/beans/beancontext/BeanContextChild.html";>java.beans.beancontext.BeanContextChild</link>
interface defines the basic interface that will be implemented (directly or
indirectly via <link
href="http://java.sun.com/j2se/1.5.0/docs/api/java/beans/beancontext/BeanContextProxy.html";>java.beans.beancontext.BeanContextProxy</link>)
by a JavaBean that wants to be contained within/access the services of a
BeanContext. It defines the basic mechanism for setting/retreiving the parent
BeanContext for a JavaBean, as well as the APIs for listening to / vetoing
property changes on the nested bean.
+ <p>The <a
href="http://java.sun.com/j2se/1.5.0/docs/api/java/beans/beancontext/BeanContextChild.html";>java.beans.beancontext.BeanContextChild</a>
interface defines the basic interface that will be implemented (directly or
indirectly via <a
href="http://java.sun.com/j2se/1.5.0/docs/api/java/beans/beancontext/BeanContextProxy.html";>java.beans.beancontext.BeanContextProxy</a>)
by a JavaBean that wants to be contained within/access the services of a
BeanContext. It defines the basic mechanism for setting/retrieving the parent
BeanContext for a JavaBean, as well as the APIs for listening to / vetoing
property changes on the nested bean.
</p>
</section><!-- BeanContextChild -->
<section><title>BeanContextServices</title>
- <p>The <link
href="http://java.sun.com/j2se/1.5.0/docs/api/java/beans/beancontext/BeanContextServices.html";>java.beans.beancontext.BeanContextServices</link>
interface derives from the BeanContext interface and defines a BeanContext
that is capable of providing services to the JavaBeans contained within it.
It defines a model for how services can be discovered and used by the contained
JavaBeans, as well as a model for how service providers can register themselves
with the context so their services will be available.
+ <p>The <a
href="http://java.sun.com/j2se/1.5.0/docs/api/java/beans/beancontext/BeanContextServices.html";>java.beans.beancontext.BeanContextServices</a>
interface derives from the BeanContext interface and defines a BeanContext
that is capable of providing services to the JavaBeans contained within it.
It defines a model for how services can be discovered and used by the contained
JavaBeans, as well as a model for how service providers can register themselves
with the context so their services will be available.
</p>
<p>Service discovery is hierarchical; if a particular BeanContext does
not implement a service requested by a contained JavaBean, but is itself
contained within another BeanContext, it will delegate the request upwards to
see if any parent context can provide the requested service.
@@ -102,10 +104,10 @@
<section><title>ControlBeanContext</title>
- <p>The <link
href="http://incubator.apache.org/beehive/apidocs/classref_controls/org/apache/beehive/controls/api/context/ControlBeanContext.html";>org.apache.beehive.controls.api.context.ControlBeanContext</link>
interface extends the base java.bean.BeanContextServices interface to add the
unique services available to JavaBeans that are Beehive Controls. These
include access to control property values bound by annotations, external
configuration, or client invocation of property accessors, as well as a unique
set of lifecycle events.
+ <p>The <a
href="http://incubator.apache.org/beehive/apidocs/classref_controls/org/apache/beehive/controls/api/context/ControlBeanContext.html";>org.apache.beehive.controls.api.context.ControlBeanContext</a>
interface extends the base java.bean.BeanContextServices interface to add the
unique services available to JavaBeans that are Beehive Controls. These
include access to control property values bound by annotations, external
configuration, or client invocation of property accessors, as well as a unique
set of lifecycle events.
</p>
- <p>Every Control is guaranteed to have an associated peer
ControlBeanContext that can be used to query Control properties, nest other
controls (either declaratively or programatticaly), and to receive lifecycle
events. This is true even if the Control is not itself nested within a parent
context.
+ <p>Every Control is guaranteed to have an associated peer
ControlBeanContext that can be used to query Control properties, nest other
controls (either declaratively or programmatically), and to receive lifecycle
events. This is true even if the Control is not itself nested within a parent
context.
</p>
<p>This peer ControlBeanContext can be obtained by declaring:</p>
@@ -114,7 +116,7 @@
@Context ControlBeanContext myContext;
</source>
- <p>within the Control Implementation class, or by calling the <link
href="http://incubator.apache.org/beehive/apidocs/classref_controls/org/apache/beehive/controls/api/bean/ControlBean.html#getControlBeanContext()">org.apache.beehive.controls.api.bean.ControlBean.getControlBeanContext()</link>
API on a Control bean instance.
+ <p>within the Control Implementation class, or by calling the <a
href="http://incubator.apache.org/beehive/apidocs/classref_controls/org/apache/beehive/controls/api/bean/ControlBean.html#getControlBeanContext()">org.apache.beehive.controls.api.bean.ControlBean.getControlBeanContext()</a>
API on a Control bean instance.
</p>
<section><title>Control Identifiers</title>
@@ -141,12 +143,12 @@
<ul>
<li>To enable external configuration based upon identifier (usage
context) rather than just a type.</li>
- <li>To locate a specific control instance within a hieararchy by
navigating the BeanContext tree based upon the ID. This can be useful in
scenarios such a external event dispatch.</li>
+ <li>To locate a specific control instance within a hieararchy by
navigating the BeanContext tree based upon the ID. This can be useful in
scenarios such as an external event dispatch.</li>
</ul>
</section><!-- Control Identity -->
- <p>The <link
href="http://incubator.apache.org/beehive/apidocs/classref_controls/org/apache/beehive/controls/runtime/bean/ControlBeanContext.html";>org.apache.beehive.controls.runtime.bean.ControlBeanContext</link>
class provides a concrete implementation of the ControlBeanContext interface
for the Controls runtime.
+ <p>The <a
href="http://incubator.apache.org/beehive/apidocs/classref_controls/org/apache/beehive/controls/runtime/bean/ControlBeanContext.html";>org.apache.beehive.controls.runtime.bean.ControlBeanContext</a>
class provides a concrete implementation of the ControlBeanContext interface
for the Controls runtime.
</p>
<p>This class is used:</p>
<ul>
@@ -158,7 +160,7 @@
<section><title>ControlBean</title>
- <p>The <link
href="http://incubator.apache.org/beehive/apidocs/classref_controls/org/apache/beehive/controls/api/bean/ControlBean.html";>org.apache.beehive.controls.api.bean.ControlBean</link>
interface defines a base interface implemented by all Controls. It provides
accessors for:
+ <p>The <a
href="http://incubator.apache.org/beehive/apidocs/classref_controls/org/apache/beehive/controls/api/bean/ControlBean.html";>org.apache.beehive.controls.api.bean.ControlBean</a>
interface defines a base interface implemented by all Controls. It provides
accessors for:
</p>
<ul>
@@ -168,26 +170,28 @@
<li>The public interface (@ControlInterface or @ControlExtension)
implemented by the Control.</li>
</ul>
- <p>The <link
href="http://incubator.apache.org/beehive/apidocs/classref_controls/org/apache/beehive/controls/runtime/bean/ControlBean.html";>org.apache.beehive.controls.runtime.bean.ControlBean</link>
class provides a concrete implementation of the ControlBean interface, and is
used as the base class for all code-generated Control JavaBeans.
+ <p>The <a
href="http://incubator.apache.org/beehive/apidocs/classref_controls/org/apache/beehive/controls/runtime/bean/ControlBean.html";>org.apache.beehive.controls.runtime.bean.ControlBean</a>
class provides a concrete implementation of the ControlBean interface, and is
used as the base class for all code-generated Control JavaBeans.
</p>
</section><!-- ControlBean -->
<section><title>ControlContainerContext</title>
- <p>The <link
href="http://incubator.apache.org/beehive/apidocs/classref_controls/org/apache/beehive/controls/runtime/bean/ControlContainerContext.html";>org.apache.beehive.controls.runtime.bean.ControlContainerContext</link>
class extends the base ControlBeanContext class to define a base integration
model (and default implementation, where appropriate) of containment and
services to integrate an external container type with the Controls runtime.
Examples of existing external containers for controls are the Servlet
container, the EJB container, the Spring bean container, ...
+ <p>The
+ <a
href="http://incubator.apache.org/beehive/apidocs/classref_controls/org/apache/beehive/controls/runtime/bean/ControlContainerContext.html";>org.apache.beehive.controls.runtime.bean.ControlContainerContext</a>
class extends the base ControlBeanContext class to define a base integration
model (and default implementation, where appropriate) of containment and
services to integrate an external container type with the Controls runtime.
Examples of existing external containers for controls are the Servlet
container,
+ the EJB container, the Spring bean container, ...
</p>
<p>An external container can provide additional services to Controls
that are running within its scope, such as a definition of how long it is OK
for Controls to acquire and hold resources, the integration of a native
container configuration model, or contextual services that are unique and
specific to the container.
</p>
- <p>For any given container, a custom subclass of the
ControlContainerContext class can be provided that defines the unique
attributes and semantics of the container for controls executing within it.
For example, the <link
href="http://incubator.apache.org/beehive/apidocs/classref_controls/org/apache/beehive/controls/runtime/servlet/ServletBeanContext.html";>ServletBeanContext</link>
class provided as part of the Controls runtime provides control containment
for the web tier. The ServletBeanContext defines the resource scope for
Controls such that any control instance can hold a resource (connection,
session, ...) for the lifetime of a single http request (but no longer).
Additionally, it exposes web-tier-specific contextual services, such as access
to the current ServletContext or active HttpServletRequest instance.
+ <p>For any given container, a custom subclass of the
ControlContainerContext class can be provided that defines the unique
attributes and semantics of the container for controls executing within it.
For example, the <a
href="http://incubator.apache.org/beehive/apidocs/classref_controls/org/apache/beehive/controls/runtime/servlet/ServletBeanContext.html";>ServletBeanContext</a>
class provided as part of the Controls runtime provides control containment
for the web tier. The ServletBeanContext defines the resource scope for
Controls such that any control instance can hold a resource (connection,
session, ...) for the lifetime of a single http request (but no longer).
Additionally, it exposes web-tier-specific contextual services, such as access
to the current ServletContext or active HttpServletRequest instance.
</p>
<p>The following section on Control Container Services describes many of
the services and behaviors that can be customized by a ControlContainerContext
subclass.
</p>
- <p>A ControlContainer context is intended to be the root context which
will contain (either directly, or indirectly via nested BeanContexts) of all
Controls used within the scope of a container instance. Generally speaking,
the relationship between container instances and ControlContainerContext
instances will be one-to-one.
+ <p>A ControlContainer context is intended to be the root context which
will contain (either directly, or indirectly via nested BeanContexts) all
Controls used within the scope of a container instance. Generally speaking,
the relationship between container instances and ControlContainerContext
instances will be one-to-one.
</p>
<p><em>Impl Note: there really should be an
org.apache.beehive.controls.spi.context.ControlContainerContext interface that
defines the basic interface for Controls containment, with the above class
acting as the concrete implementation thereof. This follows the pattern used
everywhere else, and decouples the declaration of control container
requirements from its implementation.</em>
@@ -201,7 +205,7 @@
<section><title>Control Container Services</title>
- <p>The interactions between a control and its container is best expressed
in terms of the set of functional services that the container provides to the
control. This provides a basic framework for understanding what happens at
runtime when a Control uses those services (for the Control author) as well as
the effort required to integrate these services into a specific container (for
the Control container developer).
+ <p>The interactions between a control and its container are best expressed
in terms of the set of functional services that the container provides to the
control. This provides a basic framework for understanding what happens at
runtime when a Control uses those services (for the Control author) as well as
the effort required to integrate these services into a specific container (for
the Control container developer).
</p>
<section>
Modified:
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/development/dev_mode.xml
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/development/dev_mode.xml?rev=164671&r1=164670&r2=164671&view=diff
==============================================================================
---
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/development/dev_mode.xml
(original)
+++
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/development/dev_mode.xml
Mon Apr 25 15:21:27 2005
@@ -8,7 +8,7 @@
<section>
<title>Development and Production Modes</title>
<p>Beehive applications can be run in either
<strong>development</strong> or
- <strong>production</strong> mode.</p>
+ <strong>production</strong> mode:</p>
<p>In <strong>development</strong> mode, if the tag
<code><netui:exceptions showDevModeStackTrace="true"/></code>
is present on a JSP page and an exception occurs, then
the stack trace will be
displayed.</p>
@@ -19,7 +19,7 @@
shown.</p>
<p>Similarly, assertions are
disabled by default.</p>
- <note>If you want to display the stack trace for exceptions in
all cases (whether your in production mode or development mode), you can
+ <note>If you want to display the stack trace for exceptions in
all cases (whether you're in production mode or development mode), you can
set the <code><netui:exceptions></code> tag's
<code>showStackTrace</code> attribute
to "<code>true</code>".
<br/><br/>
@@ -29,9 +29,9 @@
<section><title>Controlling the Visibility of Assertions and
Exceptions</title>
<p>Beehive uses two switches to control the visibility of
assertions and exceptions.</p>
<dl><dt><strong>-ea</strong></dt>
- <dd>Controls whether assertions enabled or not.
Assertions are
+ <dd>Controls whether assertions are enabled or not.
Assertions are
disabled by default. If assertions are
enabled, then Beehive
- assumes development mode as well, i.e.
exception stack traces are
+ assumes development mode as well: i.e.,
exception stack traces are
made visible. (See below for
enabling assertions but disabling exception
stack traces.)</dd></dl>
<dl><dt><strong>-beehive.productionmode</strong></dt>
@@ -39,12 +39,6 @@
<netui:exceptions
showDevModeStackTrace="true"/>.
By default, stack traces are not displayed.
</dd></dl>
- <!--<note>Note: until <a
-
href="http://issues.apache.org/jira/browse/BEEHIVE-462";>BEEHIVE-462</a>
- is resolved, you should substitute
- <strong><code>beehive.produtionmode</code></strong> in
the commands
- below. (Notice the misspelling:
<code>beehive.produtionmode</code>
- instead of
<code>beehive.productionmode</code>)</note>-->
<dl>
<dt>
<strong>
@@ -75,7 +69,7 @@
</strong>
</dt>
<dd>This is a case
- where the assumption made by Beehive is overriden:
assertions are
+ where the assumption made by Beehive is overridden:
assertions are
enabled, but Beehive will run in production mode. If
you have
<netui:exceptions showDevModeStackTrace="true"/> in
a page and
an exception occurs, you won't see the stack trace.</dd>
