You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by hu...@apache.org on 2001/11/03 13:24:25 UTC
cvs commit: jakarta-struts/doc/userGuide resources.xml project.xml kickstart.xml introduction.xml
husted 01/11/03 04:24:25
Modified: doc/userGuide resources.xml project.xml kickstart.xml
introduction.xml
Log:
index.xml - Add documentation section
project.xml - Move Kickstart above User Guide
kickstart - Add links to mailing archives and JGuru under Getting Help. Stylistc changes.
userguide/project.xml - Move Kickstart before Introduction
userguide/introduction.xml - Several stylistic changes, mainly to stress the use of business logic beans.
Revision Changes Path
1.11 +1 -1 jakarta-struts/doc/userGuide/resources.xml
Index: resources.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/resources.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- resources.xml 2001/11/02 11:53:18 1.10
+++ resources.xml 2001/11/03 12:24:25 1.11
@@ -233,7 +233,7 @@
<li><b>U</b><b>pco</b> -<a href="http://www.upco.co.uk">upco.co.uk</a> - <a href="mailto:Jon.Ridgway@upco.co.uk">Jon Ridgeway</a>.</li>
<li><b>viadee <font size="1">UNTERNEHMENSBERATUNG GmbH</font></b> - <a href="http://www.viadee.de/">www.viadee.de</a> - <a href="mailto:friedrich.budde@viadee.de">Frido Budde</a>.</li>
</ul>
- <p>Next: <a href="kickstart.html">Kickstart FAQ</a></p>
+ <p>Next: <a href="volunteers.html">Who We Are</a></p>
</section>
</chapter></body></document>
1.5 +1 -1 jakarta-struts/doc/userGuide/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/project.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- project.xml 2001/10/05 11:19:29 1.4
+++ project.xml 2001/11/03 12:24:25 1.5
@@ -7,12 +7,12 @@
<menu name="User's Guide">
<item name="Table of Contents" href="index.html"/>
+ <item name="Kickstart FAQ" href="kickstart.html"/>
<item name="Introduction" href="introduction.html"/>
<item name="Model Components" href="building_model.html"/>
<item name="View Components" href="building_view.html"/>
<item name="Controller Components" href="building_controller.html"/>
<item name="Resources" href="resources.html"/>
- <item name="Kickstart FAQ" href="kickstart.html"/>
<item name="Who We Are" href="volunteers.html"/>
<item name="Struts Home" href="../index.html"/>
</menu>
1.5 +9 -8 jakarta-struts/doc/userGuide/kickstart.xml
Index: kickstart.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/kickstart.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- kickstart.xml 2001/10/23 18:25:09 1.4
+++ kickstart.xml 2001/11/03 12:24:25 1.5
@@ -49,11 +49,13 @@
</section>
<section href="who" name="Who wrote Struts?">
-<p>Struts was created by Craig R. McClanahan, and donated to the Apache Software Foundation in May 2000. Craig actively leads the Struts project, and is also the lead developer on the Tomcat 4.0 project. There are now several committers to the Struts project, working cooperatively from around the globe. Other Java developers are invited to <a href="#contribute">contribute to the project</a>. Struts is an <a href="http://jakarta.apache.org/">Apache Jakarta</a> project, with the common mission to "provide commercial-quality server solutions based on the Java Platform that are developed in an open and cooperative fashion".</p>
+<p>Struts was created by Craig R. McClanahan, and donated to the Apache Software Foundation in May 2000. Craig is the primary developer of both Struts and <a href="http://jakarta.apache.org/tomcat/index.html">Tomcat 4</a>, the official reference implementation for a Java servlet container. With stable releases of Struts and Tomcat 4 in circulation, Craig is now working as the Implementation Engineer for Sun's new <a href="http://java.sun.com/pr/2001/06/pr010604-03.html">Web Services Pack</a>. </p>
+
+<p>There are now many active committers to the Struts project, working cooperatively from around the globe. Other Java developers are invited to <a href="#contribute">contribute to the project</a>. Struts is an <a href="http://jakarta.apache.org/">Apache Jakarta</a> project, with the common mission to "provide commercial-quality server solutions based on the Java Platform that are developed in an open and cooperative fashion". All told, 17 individual developers and committers contributed to the Struts 1.0 codebase.</p>
</section>
<section href="struts" name="Why is it called Struts?">
-<p>It's a reference to struts in the architechtural sense, a reminder of the nearly invisible pieces that hold up buildings, houses, and bridges.</p>
+<p>It's a reference to struts in the architectural sense, a reminder of the nearly invisible pieces that hold up buildings, houses, and bridges.</p>
</section>
<section href="license" name="How is Struts licensed?">
@@ -88,13 +90,12 @@
</section>
<section href="help" name="Where can I get help with Struts?">
-<p>The Struts package comes complete with a <a href="http://jakarta.apache.org/struts/userGuide/index.html"> users guide</a> to introduce people to the framework and its underlying technologies. Various components also have their own in-depth developers guide, to cover more advanced topics. Of course, standard "JavaDocs" are included along with the<b> full source code</b>. The <a href="http://jakarta.apache.org/site/mail.html"> Strut's mailing list</a> is also very active, and welcomes posts from new users.</p>
-<p>There are also many third-party tutorials, articles, and books that cover Struts. See our <a href="resources.html#tutorials">Resources page</a> for current listings and links</p>
+<p>The Struts package comes complete with a <a href="http://jakarta.apache.org/struts/userGuide/index.html">users guide</a> to introduce people to the framework and its underlying technologies. Various components also have their own in-depth developers guide, to cover more advanced topics. Comprehesive <a href="http://jakarta.apache.org/struts/api-1.0/index.html">Javadocs</a> are included along with the <b>full source code</b>. The <a href="http://jakarta.apache.org/site/mail.html">Strut's mailing list</a> is also very active, and welcomes posts from new users.</p>
+<p>There are also many third-party tutorials, articles, and books that cover Struts. See our <a href="resources.html#tutorials">Resources page</a> for current listings and links. Two very useful resources are the <a href="http://www.mail-archive.com/index.php3?hunt=struts">mailing list archives</a> and the <a href="http://www.jguru.com/forums/Struts">Struts Forum at JGuru</a>.</p>
</section>
<section href="support" name="Is commercial support available?">
<p>There is no official, commercial support for Struts, though third parties may offer different degrees of support. A list of Struts consultants is available on our <a href="resources.html#consultants">Resources page</a></p>
-<p>There are also many third-party tutorials, articles, and books that cover Struts. See our <a href="resources.html#tutorials">Resources page</a> for more information about these.</p>
</section>
<section href="providers" name="Are there ISPs that will host my Struts application?">
@@ -120,11 +121,11 @@
<section href="bugs" name="Where can I report bugs or make feature requests?">
<p>You can research and report outstanding fixes and feature requests using <a href="http://jakarta.apache.org/site/bugs.html">Jakarta Bugzilla</a>.</p>
<p>If you are unsure if this is in actual problem, feel free to bring it up on the list first. But to be sure an issue is resolved, always report it to <a href="http://jakarta.apache.org/site/bugs.html">Bugzilla</a>.</p>
-<p>Struts also maintains a <a href="../todo-1.1.html">TODO list</a> regarding planned features.</p>
+<p>Struts also maintains a <a href="../todo-1.1.html">TODO list</a> outlining features being planned or developed.</p>
</section>
<section href="contribute" name="How can I contribute to the development of Struts?">
-<p>Struts is distributed by the <a href="http://apache.org/">Apache Software Foundation</a>. These are the same people who distribute the Apache Web server. Like all ASF projects, Struts is managed as a "meritocracy", where everyone's contribution is welcome. Users can help other users on the <a href="http://jakarta.apache.org/site/mail.html">mailing lists</a>, <a href="http://jakarta.apache.org/site/bugs.html">report bugs</a>, and <a href="http://jakarta.apache.org/site/bugs.html">request new features</a>. Developers can contribute patches, new code, and documentation. The most active Developers may become Committers, who make the actual decisions about the Strut's codebase.</p>
+<p>Struts is distributed by the <a href="http://apache.org/">Apache Software Foundation</a>. These are the same people who distribute the Apache Web server. Like all ASF projects, Struts is managed as a "meritocracy", where everyone's contribution is welcome. Users can help other users on the <a href="http://jakarta.apache.org/site/mail.html">mailing lists</a>, <a href="http://jakarta.apache.org/site/bugs.html">report bugs</a>, and <a href="http://jakarta.apache.org/site/bugs.html">request new features</a>. Developers can contribute patches, new code, and documentation. The most active Developers may become <a href="http://jakarta.apache.org/site/roles.html">Committers</a>, who make the actual decisions about the Strut's codebase.</p>
<p>You can start by joining the Struts User list. If you enjoy participating there, then sign up for the Struts Developer list too. If you find any problems with Struts, or find a missing feature, you can enter a record to our <a href="http://jakarta.apache.org/site/bugs.html">Bugzilla</a> database.</p>
</section>
@@ -160,7 +161,7 @@
<section href="unsubscribe" name="How do I unsubscribe from the mailing list?">
<p><b>From the email account used to subscribe to the list,</b> <a href="mailto:struts-user-unsubscribe@jakarta.apache.org">send a blank message</a> to < <a href="mailto:struts-user-unsubscribe@jakarta.apache.org">struts-user-unsubscribe@jakarta.apache.org</a>>.</p>
- <p>Next: <a href="volunteers.html">Who We Are</a></p>
+ <p>Next: <a href="introduction.html">Introduction to the Users Guide</a></p>
</section>
1.7 +85 -57 jakarta-struts/doc/userGuide/introduction.xml
Index: introduction.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/introduction.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- introduction.xml 2001/10/19 05:51:09 1.6
+++ introduction.xml 2001/11/03 12:24:25 1.7
@@ -15,24 +15,37 @@
<chapter name="1. Introduction" href="introduction">
- <section name="1.1 Preface: Forward into the Past! (or a brief history of Struts)" href="preface">
-
+ <section name="1.0 Prerequisites">
<p>
- Before getting started, you should know the basics of the following
- technologies:
- </p>
+ This User Guide is written for active Web developers, and assumes a working
+ knowledge about how Java Web applications work. Before getting started, you should
+ understand the basics of these core technologies:
+ </p>
+
+ <ul>
+ <li><b>The HTTP Request/Response sequence.</b><br/>The canonical source for this
+ is <a href="http://www.ietf.org/rfc/rfc2616.txt?number=2616">RFC 2616
+ - Hypertext Transfer Protocol (HTTP/1.1)</a>.</li>
+ <li><b>Java Servlets</b>.<br/> A good place to start is the
+ <a href="http://java.sun.com/products/jsp/product.html">Sun Servlet product page</a>
+ and the <a href="http://java.sun.com/docs/books/tutorial/">Sun Java Tutorials</a>.</li>
+ <li><b>JavaServer Pages (JSP)</b>.<br/> Likewise, a good place to start is the
+ <a href="http://java.sun.com/products/jsp/product.html">Sun JSP product page</a>
+ and the <a href="http://java.sun.com/docs/books/tutorial/">Sun Java Tutorials</a>.</li>
+ <li><b>JavaBeans</b>.<br/>Many Struts classes are written as JavaBeans.
+ If you haven't worked with JavaBeans before, see the
+ <a href="http://java.sun.com/products/javabeans/">Sun JavaBean product page</a>
+ and the <a href="http://java.sun.com/docs/books/tutorial/">Sun Java Tutorials</a></li>
+ </ul>
+
+ <p>If you've created Web applications on other platforms, you can probably follow along,
+ and then visit the above references as needed. These are core technologies that
+ will be used in nearly all Java Web development projects.
+ </p>
- <ul>
- <li>The HTTP Request/Response sequence. The canonical source for this
- is <a href="http://www.ietf.org/rfc/rfc2616.txt?number=2616">RFC 2616
- - Hypertext Transfer Protocol (HTTP/1.1)</a>.</li>
- <li>Java Servlets. A good place to start is the
- <a href="http://java.sun.com/products/servlet/technical.html#tutorials">
- servlet tutorials</a>.</li>
- <li>JavaServer Pages (JSP). Again, a good place to start is the
- <a href="http://java.sun.com/products/jsp/technical.html#tutorials">
- JSP tutorials</a>.</li>
- </ul>
+ </section>
+
+ <section name="1.1 Preface: Forward into the Past! (or a brief history of Struts)" href="preface">
<p>
When Java servlets were first invented, many programmers quickly realized that they were a
@@ -111,16 +124,21 @@
<code>org.apache.struts.action.Action</code> subclasses provided by the
Struts developer. When initialized, the controller parses a configuration
resource file. The configuration resource defines (among other things)
- the action mappings for the application. The controller uses these
- mappings to turn HTTP requests into application actions.
+ the <code>org.apache.struts.action.ActionMapping</code>s for an application.
+ The controller uses these mappings to turn HTTP requests into application actions.
</p>
<p>
- At a minimum, a mapping must specify (1) a request path and (2) the object
- type to act upon the request. The Action object can handle the request and respond
+ An ActionMapping will usually specify:</p>
+ <ul>
+ <li><b>a request path</b> (or "URI"),</li>
+ <li>the <b>object type</b> (Action subclass) to act upon the request, </li>
+ <li>and other properties as needed. </li>
+ </ul>
+ <p>The Action object can handle the request and respond
to the client (usually a Web browser), or indicate that control should be forwarded
- to another action. For example, if a login succeeds, a loginAction object may wish
- to forward control to a mainMenu action.
+ elsewhere. For example, if a login succeeds, a login action may wish
+ to forward the request onto the mainMenu.
</p>
<p>
@@ -133,11 +151,12 @@
<p>
An Action object can create a shopping cart bean, add an item to the
cart, place the bean in the session collection, and then forward control to
- another action -- that may use a JSP to display the contents of the user's cart.
+ another mapping. That mapping may use a JavaServer Page to display the contents of the user's cart.
Since each client has their own session, they will each also have their own
shopping cart. In a Struts application, most of the business logic can be
- represented using JavaBeans.
- </p>
+ represented using JavaBeans. An Action can call the properties of a JavaBean
+ without knowing how it actually works. This encapsulates the business logic,
+ so that the Action can focus on error handling and where to forward control.</p>
<p>
JavaBeans can also be used to manage input forms. A key problem in designing
@@ -146,7 +165,7 @@
subclassing <code>org.apache.struts.action.ActionForm</code>, and easily store
the data for an input form in these form beans. The bean is saved in one of the
standard, shared context collections, so that it can be used by other objects,
- especially the Action object.
+ especially an Action object.
</p>
<p>
@@ -158,21 +177,21 @@
<p>
A Struts form bean is declared in the configuration resource, defined in a Java
- source file, and linked to an action mapping using a common property name. When
- a request calls for an action that uses a form bean, the controller servlet
+ source file, and linked to an ActionMapping using a common property name. When
+ a request calls for an Action that uses a form bean, the controller servlet
either retrieves or creates the form bean, and passes it to the Action object.
- The action object can then check the contents of the form bean before its input
+ The Action object can then check the contents of the form bean before its input
form is displayed, and also queue messages to be handled by the form. When
ready, the Action object can return control with a forwarding to its input
form, usually a JSP. The controller can then respond to the HTTP request and
- direct the client to the Java Server Page.
+ direct the client to the JavaServer Page.
</p>
<p>
The Struts framework includes custom tags that can automatically populate
fields from a form bean. The only thing most JavaServer Pages need to know
about the rest of the framework is the proper field names and where to submit
- the form. Components like the messages set by the Action object can be output
+ the form. Components like the messages queued by the Action can be output
using a single custom tag. Other application-specific tags can also be defined
to hide implementation details from the JSPs.
</p>
@@ -192,26 +211,36 @@
</p>
<p>
- For the simplest applications, an Action object can handle the business logic
- associated with a request. However, in most cases, an Action object should pass
- the request to another object, usually a JavaBean. To allow reuse on other
- platforms, business-logic JavaBeans should not refer to any Web application
- objects. The Action object should translate needed details from the HTTP request
- and pass those along to the business-logic beans as regular Java variables.
+ For the simplest applications, an Action object may sometimes handle the business logic
+ associated with a request. <b>However, in most cases, an Action object should
+ invoke another object, usually a JavaBean, to perform the actual business logic.</b>
+ This lets the Action focus on error handling and control flow, rather than
+ business logic. To allow reuse on other platforms, business-logic JavaBeans should not refer to any Web
+ application objects. The Action object should translate needed details from the
+ HTTP request and pass those along to the business-logic beans as regular Java
+ variables.
</p>
<p>
- In a database application, the business-logic beans might connect to and
- query the database and return the result set back to the action's servlet ... to
- be stored in a form bean ... and then displayed by the JSP. Neither the action's
- servlet nor the JSP need to know (or care) where the result set comes from.
+ In a database application, for example:
</p>
+
+ <ul>
+ <li>A business-logic bean will connect to and query the database,</li>
+ <li>The business-logic bean returns the result to the Action,</li>
+ <li>The Action stores the result in a form bean in the request,</li>
+ <li>The JavaServer Page displays the result in a HTML form.</li>
+ </ul>
+
+ <p>Neither the Action nor the JSP need to know (or care) from where
+ the result comes. They just need to know how to package and display it.
+ </p>
<p>
The rest of this Users Guide explains the various Struts components in greater
detail. The Struts release also includes several Developer Guides covering
various aspects of the frameworks, along with sample applications,
- the standard JavaDoc API, and, of course, the complete source code!
+ the standard Javadoc API, and, of course, the complete source code!
</p>
<p>
@@ -239,7 +268,7 @@
these beans may be self contained (and know how to save their state
information persistently somehow), or they may be facades that know
how to retrieve information from external sources (such as a database)
- when it is requested. Entity Enterprise JavaBeans (EJBs) are also commonly
+ when it is requested. Entity Enterprise JavaBeans (Entity EJBs) are also commonly
used to represent internal state.
</p>
@@ -253,7 +282,7 @@
that authorizes the user's credit card, and sends the order to the
warehouse to be picked and shipped. Other systems will represent the
available actions separately, perhaps as Session Enterprise JavaBeans
- (EJBs).
+ (Session EJBs).
</p>
<p>
@@ -261,9 +290,9 @@
actions might be embedded within the <code>Action</code> classes that are
part of the Controller role. This is appropriate when the logic is very
simple, or where reuse of the business logic in other environments is not
- contemplated. The Struts framework supports any of these approaches, but
- recommends separating the business logic ("what to do") from the role that
- <code>Action</code> classes play ("deciding what to do").
+ contemplated. The Struts framework supports any of these approaches, but
+ <b>strongly</b> recommends separating the business logic ("how it's done")
+ from the role that <code>Action</code> classes play ("what to do").
</p>
</section>
@@ -276,7 +305,7 @@
ability to insert dynamic content based on the interpretation (at page
request time) of special action tags. The JSP environment includes a
set of standard action tags, such as <code><jsp:useBean></code>
- whose purpose is described in the JavaServer Pages Specification. In
+ whose purpose is described in the <a href="http://java.sun.com/products/jsp/download.html">JavaServer Pages Specification</a>. In
addition, there is a standard facility to define your own tags, which
are organized into "custom tag libraries."
</p>
@@ -307,13 +336,13 @@
what business logic function is to be performed, and then delegating
responsibility for producing the next phase of the user interface to
an appropriate View component. In Struts, the primary component of the
- Controller is a servlet of class <code>ActionServlet</code>. This servlet
- is configured by defining a set of mappings (described by a Java class
- <code>ActionMapping</code>). Each mapping defines a <code>path</code>
- that is matched against the request URI of the incoming request, and the
- fully qualified class name of an <code>Action</code> class (that is, a
- Java class extending the <code>Action</code> class) which is
- responsible for performing the desired business logic, and then dispatching
+ Controller is a servlet of class <code>ActionServlet</code>. This servlet
+ is configured by defining a set of <code>ActionMappings</code>.
+ An ActionMapping defines a <code>path</code> that is matched against the
+ request URI of the incoming request, and usually specifies the
+ fully qualified class name of an Action class. All Actions
+ are subclassed from <code>org.apache.struts.action.Action</code>. Actions
+ encapsulate the business logic, interpret the outcome, and ultimately dispatch
control to the appropriate View component to create the response.
</p>
@@ -326,8 +355,7 @@
control should be forwarded so that an action method can ask for the
"Main Menu" page (for example), without knowing what the actual name of the
corresponding JSP page is. These features greatly assist you in separating
- the control logic (what do I do next) with the view logic (what is the name
- of the corresponding page).
+ the control logic (what to do) with the view logic (how it's done).
</p>
<p align="center">
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>