husted 2002/12/27 03:44:13
Modified: doc/userGuide building_model.xml
Log:
Conform line-length. No content changes.
Revision Changes Path
1.14 +311 -247 jakarta-struts/doc/userGuide/building_model.xml
Index: building_model.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/building_model.xml,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- building_model.xml 24 Dec 2002 01:50:07 -0000 1.13
+++ building_model.xml 27 Dec 2002 11:44:13 -0000 1.14
@@ -1,249 +1,312 @@
<?xml version="1.0"?>
+
+<!--
+// ======================================================================== 78
+-->
+
<document url="./building_model.xml">
- <properties>
+<properties>
<author>Craig R. McClanahan</author>
<author>Mike Schachter</author>
<author>Ted Husted</author>
<author>Martin Cooper</author>
<author>Ed Burns</author>
<title>The Struts User's Guide - Building Model Components</title>
- </properties>
+</properties>
+
+<body>
+<chapter name="2. Building Model Components" href="building_model">
- <body>
- <chapter name="2. Building Model Components" href="building_model">
+<section name="2.1 Overview" href="overview">
- <section name="2.1 Overview" href="overview">
+ <p>
+ Many requirements documents used for building web applications focus on
+ the <i>View</i>.
+ However, you should ensure that the processing required for each submitted
+ request is also clearly defined from the <i>Model's</i> perspective.
+ In general, the developer of the <i>Model</i> components will be focusing
+ on the creation of JavaBeans classes that support all of the functional
+ requirements.
+ The precise nature of the beans required by a particular application will
+ vary widely depending on those requirements, but they can generally be
+ classified into several categories discussed below.
+ However, a brief review of the concept of "scope" as it relates to beans
+ and JSP is useful first.
+ </p>
+
+</section>
+
+<section name="2.2 JavaBeans and Scope" href="javabeans">
+
+ <p>
+ Within a web-based application, JavaBeans can be stored in (and accessed
+ from) a number of different collections of "attributes".
+ Each collection has different rules for the lifetime of that collection,
+ and the visibility of the beans stored there.
+ Together, the rules defining lifetime and visibility are called the
+ <i>scope</i> of those beans.
+ The JavaServer Pages (JSP) Specification defines scope choices using
+ the following terms (with the equivalent servlet API concept defined in
+ parentheses):
+ </p>
+
+ <ul>
+
+ <li>
+ <b>page</b> - Beans that are visible within a single JSP page,
+ for the lifetime of the current request.
+ (Local variables of the <code>service</code> method)
+ </li>
+
+ <li>
+ <b>request</b> - Beans that are visible within a single JSP page,
+ as well as to any page or servlet that is included in this page,
+ or forwarded to by this page.
+ (Request attributes)
+ </li>
+
+ <li>
+ <b>session</b> - Beans that are visible to all JSP pages and
+ servlets that participate in a particular user session, across one
+ or more requests.
+ (Session attributes)
+ </li>
+
+ <li>
+ <b>application</b> - Beans that are visible to all JSP pages and
+ servlets that are part of a web application.
+ (Servlet context attributes)
+ </li>
+
+ </ul>
+
+ <p>
+ It is important to remember that JSP pages and servlets in the same
+ web application share the same sets of bean collections.
+ For example, a bean stored as a request attribute in a servlet like this:
+ </p>
+
+ <p>
+ <code>MyCart mycart = new MyCart(...);<br />
+ request.setAttribute("cart", mycart);
+ </code>
+ </p>
+
+ <p>
+ is immediately visible to a JSP page which this servlet forwards to,
+ using a standard action tag like this:
+ </p>
+
+ <p>
+ <code><jsp:useBean id="cart" scope="request"<br />
+ class="com.mycompany.MyApp.MyCart"/>
+ </code>
+ </p>
+
+</section>
+
+<section name="2.3 ActionForm Beans" href="actionform">
+
+ <blockquote>
+ <b>Note:</b> While ActionForm beans often have properties that
+ correspond to properties in your Model beans, the form beans themselves
+ should be considered a Controller component.
+ As such, they are able to transfer data between the Model and View layers.
+ </blockquote>
+
+ <p>
+ The Struts framework generally assumes that you have defined an
+ <code>ActionForm</code> bean (that is, a Java class extending the
+ <code>ActionForm</code> class) for the input forms in your
+ application.
+ <code>ActionForm</code> beans are sometimes just called "form beans".
+ These may be finely-grained objects, so that there is one
+ bean for each form, or coarsely-grained so that one bean serves
+ several forms, or even an entire application.
+ </p>
+
+ <p>
+ If you declare such beans in your Struts
+ configuration file (see "<a href="building_controller.html#config">
+ Building the Controller Components</a>"), the Struts controller servlet
+ will automatically perform the following services for you, before
+ invoking the appropriate <code>Action</code> method:
+ </p>
+
+ <ul>
+
+ <li>
+ Check in the user's session for an instance of a bean of the
+ appropriate class, under the appropriate key.
+ </li>
+
+ <li>
+ If there is no such session scope bean available, a new one is
+ automatically created and added to the user's session.
+ </li>
+
+ <li>
+ For every request parameter whose name corresponds to the name
+ of a property in the bean, the corresponding setter method will
+ be called. This operates in a manner similar to the standard
+ JSP action <code><jsp:setProperty></code> when you use the
+ asterisk wildcard to select all properties.
+ </li>
+
+ <li>
+ The updated <code>ActionForm</code> bean will be passed to the
+ <code>execute</code> method of an <code>Action</code> class
+ [<code>org.apache.struts.Action</code>], so that the values can
+ be made available to your system state and business logic beans.
+ </li>
+
+ </ul>
+
+ <p>
+ For more about coding <code>Actions</code> and <code>ActionForm</code>
+ beans, see the "<a href="building_controller.html">Building
+ Controller Components</a>" chapter.
+ </p>
+
+ <p>
+ You should note that a "form", in the sense discussed here, does not
+ necessarily correspond to a single JSP page in the user interface.
+ It is common in many applications to have a "form" (from the user's
+ perspective) that extends over multiple pages.
+ Think, for example, of the wizard style user interface that is commonly
+ used when installing new applications.
+ Struts encourages you to define a single <code>ActionForm</code> bean that
+ contains properties for all of the fields, no matter which page the field
+ is actually displayed on.
+ Likewise, the various pages of the same form should all be submitted to
+ the same Action Class.
+ If you follow these suggestions, the page designers can rearrange the
+ fields among the various pages, often without requiring changes to the
+ processing logic.
+ </p>
+
+ <p>
+ Smaller applications may only need a single ActionForm to service all of
+ its input forms.
+ Others applications might use a single ActionForm for each major subsystem
+ of the application.
+ Some teams might prefer to have a separate ActionForm class for each
+ distinct input form or workflow.
+ How many or how few ActionForms to use is entirely up to you.
+ The framework doesn't care.
+ </p>
+
+</section>
+
+<section name="2.4 System State Beans" href="system_state">
+
+ <p>
+ The actual state of a system is normally represented as a set of one or
+ more JavaBeans classes, whose properties define the current state.
+ A shopping cart system, for example, will include a bean that represents
+ the cart being maintained for each individual shopper, and will (among
+ other things) include the set of items that the shopper has currently
+ selected for purchase.
+ Separately, the system will also include different beans for the user's
+ profile information (including their credit card and ship-to addresses),
+ as well as the catalog of available items and their current inventory
+ levels.
+ </p>
+
+ <p>
+ For small scale systems, or for state information that need not be kept
+ for a long period of time, a set of system state beans may contain all the
+ knowledge that the system ever has of these particular details.
+ Or, as is often the case, the system state beans will represent
+ information that is stored permanently in some external database (such as
+ a <code>CustomerBean</code> object that corresponds to a particular row in
+ the CUSTOMERS table), and are created or removed from the server's memory
+ as needed.
+ Entity Enterprise JavaBeans are also used for this purpose in large scale
+ applications.
+ </p>
+
+</section>
+
+<section name="2.5 Business Logic Beans" href="business_logic">
+
+ <p>
+ You should encapsulate the functional logic of your application as
+ method calls on JavaBeans designed for this purpose.
+ These methods may be part of the same classes used for the system state
+ beans, or they may be in separate classes dedicated to performing the
+ logic.
+ In the latter case, you will usually need to pass the system state beans
+ to be manipulated to these methods as arguments.
+ </p>
+
+ <p>
+ For maximum code re-use, business logic beans should be designed and
+ implemented so that they do <b>not</b> know they are being executed in a
+ web application environment.
+ If you find yourself having to import a <code>javax.servlet.*</code> class
+ in your bean, you are tying this business logic to the web application
+ environment.
+ Consider rearranging things so that your <code>Action</code> classes (part
+ of the Controller role, as described below) translate all required
+ information from the HTTP request being processed into property setter
+ calls on your business logic beans, after which a call to an
+ <code>execute</code> method can be made.
+ Such a business logic class can be reused in environments other than the
+ web application for which they were initially constructed.
+ </p>
+
+ <p>
+ Depending on the complexity and scope of your application, business logic
+ beans might be ordinary JavaBeans that interact with system state beans
+ passed as arguments, or ordinary JavaBeans that access a database using
+ JDBC calls.
+ For larger applications, these beans will often be stateful or stateless
+ Enterprise JavaBeans (EJBs) instead.
+ </p>
+
+</section>
+
+<section name="2.6 Accessing Relational Databases" href="databases">
+
+ <p>
+ Ideally, the business logic beans should encapsulate the data access
+ details, including acquiring a database connection.
+ However, some application designs expect that the caller able to provide a
+ with a database connection or datasource instance.
+ When this is the case, the Struts datasource manager can make it easy for
+ your Action to produce these resources on demand.
+ </p>
+
+ <p>
+ The Struts datasource manager is configured as an element in the
+ <a href="building_controller.html#other_config">
+ Struts configuration file</a> (struts-config.xml).
+ The manager can used to deploy any connection pool that implements the
+ <code>javax.sql.DataSource</code> interface and is configurable totally
+ from JavaBean properties.
+ If your DBMS or container provides a connection pool that meets these
+ requirements, then that component might your first choice.
+ </p>
+
+ <p>
+ The Jakarta Commons dbcp's BasicDataSource
+ [<code>org.apache.commons.dbcp.BasicDataSource</code>] also works well
+ with the datasource manager, if a native component is not available.
+ The Struts distribution includes a Generic DataSource class in its util
+ package, but this is now only a wrapper around the BasicDataSource.
+ The GenericDataSource class is deprecated as of Struts 1.1 and replaced
+ by direct use of the BasicDataSource.
+ </p>
+
+ <p>
+ After the datasource is defined, here is an example of using the
+ manger to establishing a connection from within an Action's
+ <code>execute</code> method.
+ </p>
- <p>
- Many requirements documents used for building web applications
- focus on the <i>View</i>. However, you should ensure that the
- processing required for each submitted request is also clearly
- defined from the <i>Model's</i> perspective. In general, the
- developer of the <i>Model</i> components will be focusing on
- the creation of JavaBeans classes that support all of the
- functional requirements. The precise nature of the beans
- required by a particular application will vary widely
- depending on those requirements, but they can generally be
- classified into several categories discussed below. However,
- a brief review of the concept of "scope" as it relates to
- beans and JSP is useful first.
- </p>
- </section>
-
- <section name="2.2 JavaBeans and Scope" href="javabeans">
-
- <p>
- Within a web-based application, JavaBeans can be stored in (and accessed
- from) a number of different collections of "attributes". Each collection
- has different rules for the lifetime of that collection, and the visibility
- of the beans stored there. Together, the rules defining lifetime and
- visibility are called the <i>scope</i> of those beans. The JavaServer
- Pages (JSP) Specification defines scope choices using the following terms
- (with the equivalent servlet API concept defined in parentheses):
- </p>
-
- <ul>
- <li><b>page</b> - Beans that are visible within a single JSP page,
- for the lifetime of the current request. (Local variables of
- the <code>service</code> method)</li>
- <li><b>request</b> - Beans that are visible within a single JSP page,
- as well as to any page or servlet that is included in this page,
- or forwarded to by this page. (Request attributes)</li>
- <li><b>session</b> - Beans that are visible to all JSP pages and
- servlets that participate in a particular user session, across one
- or more requests. (Session attributes)</li>
- <li><b>application</b> - Beans that are visible to all JSP pages and
- servlets that are part of a web application. (Servlet context
- attributes)</li>
- </ul>
-
- <p>
- It is important to remember that JSP pages and servlets in the same
- web application share the same sets of bean collections. For example,
- a bean stored as a request attribute in a servlet like this:
- </p>
-
- <p><code>MyCart mycart = new MyCart(...);<br />
- request.setAttribute("cart", mycart);
- </code></p>
-
- <p>
- is immediately visible to a JSP page which this servlet forwards to,
- using a standard action tag like this:
- </p>
-
- <p><code><jsp:useBean id="cart" scope="request"<br />
- class="com.mycompany.MyApp.MyCart"/>
- </code></p>
- </section>
-
- <section name="2.3 ActionForm Beans" href="actionform">
-
- <blockquote>
- <b>Note:</b> While ActionForm beans often have properties that correspond
- to properties in your Model beans, the form beans themselves should
- be considered a Controller component. As such, they are able to
- transfer data between the Model and View layers.
- </blockquote>
- <p>
- The Struts framework generally assumes that you have defined an
- <code>ActionForm</code> bean (that is, a Java class extending the
- <code>ActionForm</code> class) for the input forms in your
- application. <code>ActionForm</code> beans are sometimes just called
- "form beans". These may be finely-grained objects, so that there is one
- bean for each form, or coarsely-grained so that one bean serves
- several forms, or even an entire application.
- </p>
- <p>
- If you declare such beans in your Struts
- configuration file (see "<a href="building_controller.html#config">
- Building the Controller Components</a>"), the Struts controller servlet
- will automatically perform the following services for you, before
- invoking the appropriate <code>Action</code> method:
- </p>
-
- <ul>
- <li>Check in the user's session for an instance of a bean of the
- appropriate class, under the appropriate key.</li>
- <li>If there is no such session scope bean available, a new one is
- automatically created and added to the user's session.</li>
- <li>For every request parameter whose name corresponds to the name
- of a property in the bean, the corresponding setter method will
- be called. This operates in a manner similar to the standard
- JSP action <code><jsp:setProperty></code> when you use the
- asterisk wildcard to select all properties.</li>
- <li>The updated <code>ActionForm</code> bean will be passed to the
- <code>execute</code> method of an <code>Action</code> class
- [<code>org.apache.struts.Action</code>], so that the values can
- be made available to your system state and business logic beans.</li>
- </ul>
-
- <p>
- For more about coding <code>Actions</code> and <code>ActionForm</code>
- beans, see the "<a href="building_controller.html">Building
- Controller Components</a>" chapter.
- </p>
-
- <p>
- You should note that a "form", in the sense discussed here, does not
- necessarily correspond to a single JSP page in the user interface. It is
- common in many applications to have a "form" (from the user's perspective)
- that extends over multiple pages. Think, for example, of the wizard style
- user interface that is commonly used when installing new applications.
Struts
- encourages you to define a single <code>ActionForm</code> bean that contains
- properties for all of the fields, no matter which page the field is actually
- displayed on. Likewise, the various pages of the same form should all be
- submitted to the same Action Class. If you follow these suggestions, the
- page designers can rearrange the fields among the various pages, often
without
- requiring changes to the processing logic.
- </p>
-
- <p>
- Smaller applications may only need a single ActionForm to service all of
- its input forms. Others applications might use a single ActionForm for each
- major subsystem of the application. Some teams might prefer to have a
- separate ActionForm class for each distinct input form or workflow. How many
- or how few ActionForms to use is entirely up to you. The framework doesn't
- care.
- </p>
-
- </section>
-
- <section name="2.4 System State Beans" href="system_state">
-
- <p>
- The actual state of a system is normally represented as a set of one or
- more JavaBeans classes, whose properties define the current state. A
- shopping cart system, for example, will include a bean that represents the
- cart being maintained for each individual shopper, and will (among other
- things) include the set of items that the shopper has currently selected
- for purchase. Separately, the system will also include different beans
- for the user's profile information (including their credit card and ship-to
- addresses), as well as the catalog of available items and their current
- inventory levels.
- </p>
-
- <p>
- For small scale systems, or for state information that need not be kept
- for a long period of time, a set of system state beans may contain all the
- knowledge that the system ever has of these particular details. Or, as is
- often the case, the system state beans will represent information that is
- stored permanently in some external database (such as a
<code>CustomerBean</code> object
- that corresponds to a particular row in the CUSTOMERS table), and are
- created or removed from the server's memory as needed. Entity Enterprise
- JavaBeans are also used for this purpose in large scale applications.
- </p>
- </section>
-
- <section name="2.5 Business Logic Beans" href="business_logic">
-
- <p>
- You should encapsulate the functional logic of your application as
- method calls on JavaBeans designed for this purpose. These methods may
- be part of the same classes used for the system state beans, or they may
- be in separate classes dedicated to performing the logic. In the latter
- case, you will usually need to pass the system state beans to be manipulated
- to these methods as arguments.
- </p>
-
- <p>
- For maximum code re-use, business logic beans should be designed and
- implemented so that they do <b>not</b> know they are being executed in a
- web application environment. If you find yourself having to import a
- <code>javax.servlet.*</code> class in your bean, you
- are tying this business logic to the web application environment. Consider
- rearranging things so that your <code>Action</code> classes (part of the
- Controller role, as described below) translate all required information
- from the HTTP request being processed into property setter calls on your
- business logic beans, after which a call to an <code>execute</code> method
- can be made. Such a business logic class can be reused in environments
- other than the web application for which they were initially constructed.
- </p>
-
- <p>
- Depending on the complexity and scope of your application, business logic
- beans might be ordinary JavaBeans that interact with system state beans
- passed as arguments, or ordinary JavaBeans that access a database using
- JDBC calls. For larger applications, these beans will often be stateful
- or stateless Enterprise JavaBeans (EJBs) instead.
- </p>
- </section>
-
- <section name="2.6 Accessing Relational Databases" href="databases">
-
- <p>
- Ideally, the business logic beans should encapsulate the data access
- details, including acquiring a database connection. However, some
- application designs expect that the caller able to provide a
- with a database connection or datasource instance. When this is the
- case, the Struts datasource manager can make it easy for your Action
- to produce these resources on demand.
- </p>
- <p>
- The Struts datasource manager is configured as an element in the
- <a href="building_controller.html#other_config">Struts configuration
file</a>
- (struts-config.xml). The manager can
- used to deploy any connection pool that implements the
- <code>javax.sql.DataSource</code> interface and is configurable totally
- from JavaBean properties. If your DBMS or container provides a
- connection pool that meets these requirements, then that component
- might your first choice.
- </p>
- <p>
- The Jakarta Commons dbcp's BasicDataSource
- [org.apache.commons.dbcp.BasicDataSource] also works well with the
- datasource manager, if a native component is not available. The Struts
- distribution includes a Generic DataSource class in its util
- package, but this is now only a wrapper around the BasicDataSource. The
- GenericDataSource class is deprecated as of Struts 1.1 and replaced by
- direct use of the BasicDataSource.
- </p>
- <p>
- After the datasource is defined, here is an example of using the
- manger to establishing a connection from within an Action's
<code>execute</code> method.
- </p>
-<pre>
+<pre><code>
public ActionForward
execute(ActionMapping mapping,
ActionForm form,
@@ -271,20 +334,21 @@
}
}
}
-</pre>
+</code></pre>
- <p>
- Note that you can define as many datasource objects as your application
requires and
- refer to each using a logical name. This can be useful in providing better
security or
- scalability, or even to test datasource implementations against each other.
- </p>
-
- <p align="center">
- Next: <a href="building_view.html">Building View Components</a>
- </p>
+ <p>
+ Note that you can define as many datasource objects as your application
+ requires and refer to each using a logical name.
+ This can be useful in providing better security or scalability, or even
+ to test datasource implementations against each other.
+ </p>
+
+ <p align="center">
+ Next: <a href="building_view.html">Building View Components</a>
+ </p>
- </section>
+</section>
- </chapter>
- </body>
+</chapter>
+</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
