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 2002/11/30 15:30:28 UTC
cvs commit: jakarta-struts/doc/userGuide preface.xml building_controller.xml building_apps.xml
husted 2002/11/30 06:30:28
Modified: doc/userGuide preface.xml building_controller.xml
building_apps.xml
Log:
Nix some TODOs.
Revision Changes Path
1.15 +252 -124 jakarta-struts/doc/userGuide/preface.xml
Index: preface.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/preface.xml,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- preface.xml 29 Nov 2002 21:27:57 -0000 1.14
+++ preface.xml 30 Nov 2002 14:30:27 -0000 1.15
@@ -31,9 +31,10 @@
<li><a href="#xml">Extensible Markup Language</a></li>
</ul>
- <p>This chapter briefly defines each of these technologies, but does not describe them in
- detail. For your convenience, links to further information about each component are also
- provided.</p>
+ <p>
+ This chapter briefly defines each of these technologies but does not describe them in detail.
+ For your convenience, links to further information are provided if you would like to learn more about a technology.
+ </p>
<p><a target="#jwst"></a>If you are familiar with Java, but not these technologies,
the best overall starting point is
@@ -90,7 +91,7 @@
Frameworks like Struts abstract much of these nuts and bolts, but it is important to understand
what is happening behind the scenes. </p>
- <p>If you are not familiar with the HTTP Request/Response cycle, we <b>strongly</b> recommend the
+ <p>If you are not familiar with the HTTP request/response cycle, we <b>strongly</b> recommend the
<a href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/HTTP.html#63796">
HTTP Overview</a> in the JWST.
</p>
@@ -208,9 +209,13 @@
DynaBeans combine the extensibility of JavaBeans with the flexbility of a Map.
Defining even the simplest JavaBean requires defining a new class and coding a field and two methods for each property.
The properties of a DynaBean can be configured via an XML descriptor.
- The virtual properties of a DynaBean can't be called by standard Java methods, but can be used to roundtrip properties to HTML forms.
- In many cases, Struts DynaForms can be configured entirely through XML.
- This means you can avoid creating a formal subclass just to store a few simple properties.
+ The virtual properties of a DynaBean can't be called by standard Java methods,
+ but work well with components that rely on relfection and introspection.
+ </p>
+
+ <p>
+ In a Struts application, you can use DynaBeans to describe your HTML forms.
+ This stategy can avoid creating a formal JavaBean subclass to store a few simple properties.
</p>
<p>
@@ -255,45 +260,40 @@
</section>
<section name="0.7 Java Servlets" href="servlets">
- <p>Much of the <a href="#cycle">HTTP Request/Response cycle</a> nuts-and-bolts are handled by Sun's
- <a href="http://java.sun.com/products/servlet/">Java Servlet</a> platform. This casts HTTP
- into an object-orientated form so that developers can better concentrate on what
- they need their application to do -- rather than the mechanics of HTTP.</p>
-
- <p>Struts provides a ready-to-use servlet for your application. As a Struts developer, you
- can then just write objects that the Struts servlet calls when needed. But it is still
- helpful to understand the basics of what servlets are and the role they play in a Java
- web application.</p>
-
- <p>For more about Java Servlets, see </p>
-
- <ul>
- <li><a href="http://java.sun.com/products/servlet/"><strong>The
- Java Servlet Technology</strong></a> page at
- <code>java.sun.com</code></li>
- <li><a href="http://java.sun.com/products/servlet/download/"><strong>The
- Servlet 2.2 and 2.3 Specifications</strong></a> download page at
- <code>java.sun.com</code></li>
- <li><a href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/Servlets.html">
- <b>Java Servlet Technology</b></a> in the Java Web Services Tutorial.</li>
- <li><a href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/WebApp.html">
- <b>Web Applications</b></a> in the Java Web Services Tutorial.</li>
- </ul>
+ <p>
+ Since Java is an object-orientated language, the
+ <a href="http://java.sun.com/products/servlet/">Java Servlet</a>
+ platform strives to cast HTTP into an object-orientated form.
+ This strategy makes it easier for Java developers to concentrate on what they need their application to do --
+ rather than the mechanics of HTTP.
+ </p>
+
+ <p>
+ HTTP provides a standard mechanism for extending servers called the Common Gateway Interface, or CGI.
+ The server can pass a request to a CGI-aware program, and the program will pass back a response.
+ Likewise, a Java-aware server can pass a request to a servlet container.
+ The container can fulfill the request or it can pass the request back to the HTTP server.
+ The container decides whether it can handle the request by checking its list of servlets.
+ If there is a servlet registered for the request, the container passes the request to the servlet.
+ </p>
+
+ <p>
+ When a request comes in, the container checks to see if there is a servlet registered for that request.
+ If there is a match,
+ the request is given to the servlet.
+ If not, the request is returned to the HTTP server.
+ </p>
+
+ <p>
+ It's the container's job to manages the servlet lifecycle.
+ The container creates the servlets, invokes the servlets, and ultimately disposes the servlets.
+ </p>
- <section name="0.7.1 Servlets" href="servlets">
+ <p>
+ A servlet is generally a subclass of <code>javax.servlet.http.HttpServlet</code>.
+ A servlet must implement four methods, which are invoked by the container as needed:
+ </p>
- <p>A <em>servlet</em> is a web component, managed by a <em>servlet
- container</em> (or web container), that generates dynamic content.
- An instance of each defined servlet is created for you the first time
- it is requested (or at application startup, depending on a setting in
- the web application deployment descriptor), and is used to process
- zero or more requests that are <em>mapped</em> to that servlet by
- a <code><servlet-mapping></code> element in the web application
- deployment descriptor.</p>
-
- <p>A servlet is generally a subclass of
- <code>javax.servlet.http.HttpServlet</code> and must implement the
- following methods:</p>
<ul>
<li><strong>public void init(ServletConfig config)</strong> - Called by the
servlet container when the servlet instance is first created, and
@@ -311,24 +311,58 @@
such as when a web application is being undeployed or when the
entire container is being shut down.</li>
</ul>
+
+ <p>
+ Struts provides a ready-to-use servlet for your application [<code>org.apache.struts.action.ActionServlet</code>].
+ As a Struts developer, you can then just write objects that the Struts ActionServlet calls when needed.
+ But it is still helpful to understand the basics of what servlets are,
+ and the role they play in a Java web application.
+ </p>
+
+ <p>
+ For more about Java Servlets, see:
+ </p>
- <p>Because there is only a single instance of a particular servlet
- running, it is quite common for several calls to the <code>doGet()</code>
- or <code>doPost()</code> methods to be occurring at the same time (on
- separate threads). Therefore, these methods (and any methods they call)
- must be programmed in a <em>thread-safe</em> manner.</p>
-
- <p>Struts includes a single servlet
- (<code>org.apache.struts.action.ActionServlet</code>) that acts as a
- Controller in the Model-View-Controller architecture. In addition, if
- you are using them, each JSP page you create is automatically converted
- into a servlet.</p>
+ <ul>
+ <li><a href="http://java.sun.com/products/servlet/"><strong>The
+ Java Servlet Technology</strong></a> page at
+ <code>java.sun.com</code></li>
+ <li><a href="http://java.sun.com/products/servlet/download/"><strong>The
+ Servlet 2.2 and 2.3 Specifications</strong></a> download page at
+ <code>java.sun.com</code></li>
+ <li><a href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/Servlets.html">
+ <b>Java Servlet Technology</b></a> in the Java Web Services Tutorial.</li>
+ <li><a href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/WebApp.html">
+ <b>Web Applications</b></a> in the Java Web Services Tutorial.</li>
+ </ul>
- </section>
+ </section>
+
+ <section name="0.7.1 Servlets and threads" href="threads">
+
+ <p>
+ To boost performance, the container can multi-thread servlets.
+ Only one instance of a particular servlet is created,
+ and each request for that servlet passes through the same object.
+ This strategy helps the container make the best use of available resources.
+ The tradeoff is that the servlet's <code>doGet()</code> and <code>doPost()</code> methods must be programmed in a <em>thread-safe</em> manner.
+ </p>
+
+ <p>
+ For more about servlets and thread-safety, see:
+ </p>
+
+ <ul>
+ <li>
+ <a href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/Servlets5.html#64386">Controlling Concurrent Access to Shared Resources</a> in JWST.
+ </li>
+ </ul>
+
+ </section>
<section name="0.7.2 Servlet Context" href="context">
- <p>The <em>ServletContext</em> interface defines a servlet's view of
+ <p>The <em>ServletContext</em> interface [<code>javax.servlet.ServletContext</code>] defines a servlet's view of
the web application within which the servlet is running. It is
accessible in a servlet via the <code>getServletConfig()</code> method,
and in a JSP page as the <code>application</code> implicit variable.
@@ -349,23 +383,31 @@
</li>
</ul>
- <p>See the Javadocs for <code>javax.servlet.ServletContext</code>
- for more information.</p>
+ <p>
+ For more about the servlet context, see:
+ </p>
+
+ <ul>
+ <li>
+ <a href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/Servlets10.html#64724">Accessing the Web Context</a> in JWST.
+ </li>
+ </ul>
</section>
<section name="0.7.3 Servlet Request" href="request">
<p>Each request processed by a servlet is represented by a Java
- interface, normally a <code>javax.servlet.http.HttpServletRequest</code>.
- The request interface provides an object oriented mechanism to access
+ interface, normally a <code>HttpServletRequest</code>
+ [<code>javax.servlet.http.HttpServletRequest</code>].
+ The request interface provides an object-oriented mechanism to access
all of the information that was included in the underlying HTTP request,
including:</p>
<ul>
<li><em>Cookies</em> - The set of cookies included with this request
are available via the <code>getCookies()</code> method.</li>
<li><em>Headers</em> - HTTP headers that were included with
- the request are accessible by name. You can enumerate the names
+ the request are accessible by name. You can enumerate the names
of all included headers.</li>
<li><em>Parameters</em> - Request parameters, including those from
the query string portion of the URL and from the embedded content
@@ -388,29 +430,36 @@
<p>In addition, servlet requests support <em>request attributes</em>
(from JSP, these are "request scope beans"), analogous to the servlet
- context attributes described above. Request attributes are often used
+ context attributes described above. Request attributes are often used
to communicate state information from a business logic class that
generates it to a view component (such as a JSP page) that will use
the information to produce the corresponding response.</p>
<p>The servlet container guarantees that a particular request will
- be processed by a servlet on a single thread. Therefore, you do not
+ be processed by a servlet on a single thread. Therefore, you do not
generally have to worry about the thread safety of your access to
request properties and attributes.</p>
- <p>See the Javadocs for <code>javax.servlet.ServletRequest</code> and
- <code>javax.servlet.http.HttpServletRequest</code> for more
- information.</p>
+ <p>
+ For more about the servlet request, see:
+ </p>
+
+ <ul>
+ <li>
+ <a href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/Servlets7.html#64433">Getting Information from Requests</a> in JWST.
+ </li>
+ </ul>
</section>
<section name="0.7.4 Servlet Response" href="response">
- <p>The primary purpose of a Servlet is to process an incoming
- <a href="#request">Servlet Request</a> and convert it into a
- corresponding response. This is performed by calling appropriate
- methods on the <code>javax.servlet.http.HttpServletResponse</code>
- interface. Available methods let you:</p>
+ <p>The primary purpose of a servlet is to process an incoming
+ <a href="#request">Servlet Request</a> [<code>javax.servlet.http.HttpServletRequest</code>]
+ and convert it into a
+ corresponding response. This is performed by calling appropriate
+ methods on the servlet response [<code>javax.servlet.http.HttpServletResponse</code>]
+ interface. Available methods let you:</p>
<ul>
<li><em>Set Headers</em> - You can set HTTP headers that will be
included in the response. The most important header is the
@@ -431,35 +480,50 @@
<p>An important principle in using the servlet response APIs is that
any methods you call to manipulate headers or cookies
<strong>MUST</strong> be performed before the first buffer-full of
- content has been flushed to the client. The reason for this restriction
+ content has been flushed to the client. The reason for this restriction
is that such information is transmitted at the beginning of the HTTP
response, so trying things like adding a header after the headers have
already been sent will not be effective.</p>
- <p>When you are using JSP pages (which is the typical mechanism for
- producing a response when using Struts), you will not generally
- use the servlet response APIs directly. Instead, the JSP page compiler
- in your servlet container will convert your page into a servlet that
- writes the content of the JSP page to the response, interspersing dynamic
- information where you have called out JSP custom tags (such as
- <code><bean:message></code> or <code><html:text></code>)
- in your page.</p>
-
- <p>See the Javadocs for <code>javax.servlet.ServletRequest</code> and
- <code>javax.servlet.http.HttpServletRequest</code> for more
- information.</p>
-
+ <p>
+ When you are using presentation pages in a Model 2 application,
+ you will not generally use the servlet response APIs directly.
+ In the case of JavaServerPages, the JSP page compiler
+ in your servlet container will convert your page into a servlet.
+ The JSP servlet renders the response, interspersing dynamic
+ information where you have interposed JSP custom tags.
+ </p>
+
+ <p>
+ Other presentation systems, like Velocity Tools for Struts,
+ may delegate rendering the response to a specialized serlvet,
+ but the same pattern holds true.
+ You create a template,
+ and the dynamic response is generated automatically from the template.
+ </p>
+
+ <p>
+ For more about the servlet response, see:
+ </p>
+
+ <ul>
+ <li>
+ <a href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/Servlets7.html#64531">Constructing Responses</a> in JWST.
+ </li>
+ </ul>
+
</section>
<section name="0.7.5 Filtering" href="filter">
<p>If you are using a servlet container based on version
<strong>2.3</strong> or later of the Servlet Specification (such as
- Tomcat 4.x), you can take advantage of the new Filter APIs that
+ Tomcat 4.x), you can take advantage of the new Filter APIs
+ [<code>javax.servlet.Filter</code>] that
let you compose a set of components that will process a request or
- response. Filters are aggregated into a chain in which each filter
+ response. Filters are aggregated into a chain in which each filter
has a chance to process the request and response before and after
- it is processed by subsequent fitlers (and the servlet that is ultimately
+ it is processed by subsequent filters (and the servlet that is ultimately
called).</p>
<p>Struts 1.0 and 1.1 require only version 2.2 or later of the
@@ -469,18 +533,25 @@
container. It is very likely that future versions of Struts will
require a Servlet 2.3 or later container, so that Struts itself
can utilize filters.</p>
+
+ <p>
+ For more about filters, see:
+ </p>
- <p>See the Javadocs for <code>javax.servlet.Filter</code> for more
- information.</p>
+ <ul>
+ <li>
+ <a href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/Servlets8.html#64572">Filtering Requests and Responses</a>
+ </li>
+ </ul>
</section>
<section name="0.7.6 Sessions" href="session">
- <p>One of the key characteristics of the HTTP protocol is that it is
- <em>stateless</em>. In other words, there is nothing built in to
+ <p>One of the key characteristics of HTTP is that it is
+ <em>stateless</em>. In other words, there is nothing built in to
HTTP that identifies a subsequent request from the same user as being
- related to a previous request from that user. This makes building an
+ related to a previous request from that user. This makes building an
application that wants to engage in a conversation with the user over
several requests to be somewhat difficult.</p>
@@ -491,13 +562,13 @@
URL rewriting) to ensure that the next request from the same user will
include the <em>session id</em> for this session, so that state
information saved in the session can be associated with multiple
- requests. This state information is stored in <em>session
+ requests. This state information is stored in <em>session
attributes</em> (in JSP, they are known as "session scope beans").</p>
<p>To avoid occupying resources forever when a user fails to complete
an interaction, sessions have a configurable <em>timeout interval</em>.
If the time gap between two requests exceeds this interval, the session
- will be timed out, and all session attributes removed. You define a
+ will be timed out, and all session attributes removed. You define a
default session timeout in your web application deployment descriptor,
and you can dynamically change it for a particular session by calling
the <code>setMaxInactiveInterval()</code> method.</p>
@@ -505,54 +576,102 @@
<p>Unlike requests, you need to be concerned about thread safety on
your session attributes (the methods these beans provide, not the
<code>getAttribute()</code> and <code>setAttribute()</code> methods
- of the session itself). It is surprisingly easy for there to be
+ of the session itself). It is surprisingly easy for there to be
multiple simultaneous requests from the same user, which will therefore
access the same session.</p>
<p>Another important consideration is that session attributes occupy
- memory in your server <em>in between</em> requests. This can have
+ memory in your server <em>in between</em> requests. This can have
an impact on the number of simultaneous users that your application can
- support. If your application requirements include very large numbers of
+ support. If your application requirements include very large numbers of
simultaneous users, you will likely want to minimize your use of
session attributes, in an effort to control the overall amount of memory
required to support your application.</p>
-
- <p>See the Javadocs for <code>javax.servlet.http.HttpSession</code>
- for more information.</p>
+
+ <p>
+ For more about sessions, see:
+ </p>
+ <ul>
+ <li>
+ <a href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/Servlets11.html#64744">Maintaining Client State</a> in JWST
+ </li>
+ <li>
+ <a href="http://java.sun.com/products/servlet/2.1/api/javax.servlet.http.HttpSession.html"><code>javax.servlet.http.HttpSession</code></a>
+ </li>
+ </ul>
</section>
<section name="0.7.7 Dispatching Requests" href="dispatch">
- <p>[:TODO:]</p>
+ <p>
+ The Java Servlet specification extends the HTTP request/response cycle by allowing the request to be dispatched,
+ or forwarded, between resources.
+ Struts uses this feature to pass a request through specialized components,
+ each handling one aspect of the response.
+ In the normal course, a request may pass through a controller object, a model object,
+ and finaly to a view object as part of a single request/response cycle.
+ </p>
</section>
<section name="0.7.8 Web Applications" href="webapp">
- <p>[:TODO:]</p>
+ <p>
+ Just as a HTTP server can be used to host several distinct web sites,
+ a servlet container can be used to host more than one web application.
+ The Java servlet platform provides a well-defined mechanism for organizing and deploying web applications.
+ Each application runs in its own namespace so that they can be developed and deployed separately.
+ A web application can be assembled into a Web Application Archive, or WAR file.
+ The single WAR can be uploaded to the server and automatically deployed.
+ </p>
+
+ <p>
+ For more about web applications, see:
+ </p>
+ <ul>
+ <li>
+ <a href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/WebApp.html#76431">Web Applications</a> in JWST
+ </li>
+ </ul>
</section>
- <section name="0.7.9 Application Lifecycle Events" href="events">
-
- <p>[:TODO:]</p>
+ <section name="0.7.9 Web application deployment descriptor (web.xml)" href="events">
+ <p>
+ Most aspects of an application's lifecycle are configured through an XML document called the Web application deployment descriptor.
+ The schema of the descriptor, or web.xml, is given by the Java servlet specification.
+ </p>
+
+ <p>
+ For more about the web.xml and application lifecycle events, see:
+ </p>
+ <ul>
+ <li>
+ <a href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/WebApp2.html#64550">Web Application Life Cycle</a> in JWST
+ </li>
+ </ul>
+
</section>
- <section name="0.7.10 Security" href="security">
+ <section name="0.7.10 Security" href="security">
- <p>[:TODO:]</p>
+ <p>
+ One detail that can be configured in the Web application deployment descriptor is container-managed security.
+ Declarative security can be used to protect requests for URIs that match given patterns.
+ Progmatic security can be used to fine-tune security make authorization decisions based on the time of day,
+ the parameters of a call, or the internal state of a Web component.
+ It can also be used to restrict authentification based on information in a database.
+ </p>
- <p>For more information about container managed security, see:</p>
+ <p>For more information about container-managed security, see:</p>
<ul>
<li><a href="http://java.sun.com/webservices/docs/1.0/tutorial/WebAppSecurity.html">
- <strong>Web Application Security</strong></a> in the
- Java Web Services Tutorial</li>
+ Web Application Security</a> in the Java Web Services Tutorial
+ </li>
</ul>
- </section>
-
</section>
<section name="0.8 JavaServer Pages and JSP Tag Libraries" href="jsp">
@@ -594,11 +713,11 @@
</p>
<p>
- One of the contributed libraries that comes with the Struts distribution,
- called <strong>Struts-EL</strong>, is specifically designed to work well
- with the JavaServer Pages Standard Tag Library. In particular, it uses
+ One of the contributed libraries available for Struts is <strong>Struts-EL</strong>.
+ This taglib is specifically designed to work well
+ with the JavaServer Pages Standard Tag Library. In particular, it uses
the same "expression language" engine for evaluating tag attribute values
- as the JSTL. This is in contrast to the main Struts tag library, which
+ as the JSTL. This is in contrast to the original Struts tag library, which
can only use "rtexprvalue"s (runtime scriptlet expressions) for dynamic
attribute values.
</p>
@@ -613,7 +732,7 @@
<section name="0.9 Extensible Markup Language (XML)" href="xml">
<p>The features provided by the Struts framework relies on a number of objects that are
- usually deployed using files written in
+ usually deployed using a configuration file written in
<a href="http://www.w3.org/XML/">Extensible Markup Language</a>. XML is also used to
configure Java web applications; so, this is yet another familiar approach.
</p>
@@ -628,12 +747,22 @@
<a href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/JAXPIntro.html">Java API for XML Processing</a> in the Java Web Services Tutorial.
While the framework makes good use of this API internally, it is not something most Struts developers
would use when writing their own applications.</p>
+
+ </section>
<section name="0.9.1 Descriptors" href="descriptors">
- <p>[:TODO:]</p>
-
- </section>
+ <p>
+ When Java applications use XML configuration files,
+ the elements are most often used as <em>descriptors</em>.
+ The application does not use the XML elements directly.
+ The elements are used to create and configure (or deploy) Java objects.
+ </p>
+
+ <p>
+ The Java Servlet platform uses an XML configuration file to deploy servlets (among other things).
+ Likewise, Struts uses an XML configuration file to deploy objects used by the framework.
+ </p>
</section>
@@ -688,5 +817,4 @@
</section>
</chapter>
- </body>
-</document>
+ </body></document>
1.47 +273 -228 jakarta-struts/doc/userGuide/building_controller.xml
Index: building_controller.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/building_controller.xml,v
retrieving revision 1.46
retrieving revision 1.47
diff -u -r1.46 -r1.47
--- building_controller.xml 16 Nov 2002 11:19:14 -0000 1.46
+++ building_controller.xml 30 Nov 2002 14:30:27 -0000 1.47
@@ -109,9 +109,17 @@
<p>For example, add the following to struts-config.xml for a UserForm bean that stores a user's given and family names:</p>
<pre>
<![CDATA[
-<form-bean name="UserForm" type="org.apache.struts.action.DynaActionForm">
- <form-property name="givenName" type="java.lang.String" initial="John"/>
- <form-property name="familyName" type="java.lang.String" initial="Smith"/>
+<form-bean
+ name="UserForm"
+ type="org.apache.struts.action.DynaActionForm">
+ <form-property
+ name="givenName"
+ type="java.lang.String"
+ initial="John"/>
+ <form-property
+ name="familyName"
+ type="java.lang.String"
+ initial="Smith"/>
</form-bean>
]]>
</pre>
@@ -441,11 +449,14 @@
Your execute method should process the Exception and return an ActionForward
object to tell Struts where to forward to next. Then you configure your
handler in struts-config.xml like this:<br/>
- <pre>
- <global-exceptions>
- <exception key="some.key" type="java.io.IOException" handler="com.yourcorp.ExceptionHandler"/>
- </global-exceptions>
- </pre>
+ <pre><![CDATA[
+ <global-exceptions>
+ <exception
+ key="some.key"
+ type="java.io.IOException"
+ handler="com.yourcorp.ExceptionHandler">
+ </global-exceptions>
+ ]]></pre>
<br/>
That configuration says that com.yourcorp.ExceptionHandler.execute() will be called
when any IOException is thrown by an Action. The key is a key from your message resources
@@ -630,30 +641,32 @@
are left out:
</p>
-<pre>
-<struts-config>
- <form-beans>
- <form-bean
+<pre><![CDATA[
+<struts-config>
+ <form-beans>
+ <form-bean
name="logonForm"
type="org.apache.struts.example.LogonForm" />
- </form-beans>
- <global-forwards
+ </form-beans>
+ <global-forwards
type="org.apache.struts.action.ActionForward" />
- <forward name="logon" path="/logon.jsp"
- redirect="false" />
- </global-forwards>
- <action-mappings>
- <action
- path="/logon"
- type="org.apache.struts.example.LogonAction"
- name="logonForm"
- scope="request"
- input="/logon.jsp"
- unknown="false"
- validate="true" />
- </action-mappings>
-</struts-config>
-</pre>
+ <forward
+ name="logon"
+ path="/logon.jsp"
+ redirect="false" />
+ </global-forwards>
+ <action-mappings>
+ <action
+ path="/logon"
+ type="org.apache.struts.example.LogonAction"
+ name="logonForm"
+ scope="request"
+ input="/logon.jsp"
+ unknown="false"
+ validate="true" />
+ </action-mappings>
+</struts-config>
+]]></pre>
<p>
First the form bean is defined. A basic bean of class "<code>org.apache.struts.example.LogonForm</code>"
@@ -679,17 +692,18 @@
application, many actions include a local "success" and/or "failure" forward as
part of an Action mapping.
</p>
-<pre>
-<!-- Edit mail subscription -->
-<action path="/editSubscription"
+<pre><![CDATA[
+<!-- Edit mail subscription -->
+<action
+ path="/editSubscription"
type="org.apache.struts.example.EditSubscriptionAction"
name="subscriptionForm"
scope="request"
validate="false">
- <forward name="failure" path="/mainMenu.jsp"/>
- <forward name="success" path="/subscription.jsp"/>
- </action>
-</pre>
+ <forward name="failure" path="/mainMenu.jsp"/>
+ <forward name="success" path="/subscription.jsp"/>
+ </action>
+]]></pre>
<p>Using just these two extra properties, the <code>Action</code> classes in the example
application are almost totally independent of the actual names of the JSP pages
@@ -704,24 +718,25 @@
<section name="4.6.2 Controller Configuration" href="controller_config">
<p>
- The <controller> element allows you to configure the ActionServlet. Many of the controller
+ The <controller> element allows you to configure the ActionServlet. Many of the controller
parameters were previously defined by servlet init. parameters in your web.xml file but have been
- moved to this section of struts-config.xml. For full details on available parameters see the
+ moved to this section of struts-config.xml. For full details on available parameters see the
struts-config_1_1.dtd.
</p>
<p>
This example uses the default values for several controller parameters. If you only want default
- behavior you can omit the controller section altogether.<br/>
- <pre>
- <controller
+ behavior you can omit the controller section altogether.
+ </p>
+ <pre><![CDATA[
+ <controller
processorClass="org.apache.struts.action.RequestProcessor"
debug="0"
- contentType="text/html"/>
- </pre>
- </p>
+ contentType="text/html"/>;
+ ]]></pre>
</section>
- <section name="4.6.3 Message Resources Configuration" href="resources_config">
+ <section name="4.6.3 Message Resources Configuration" href="resources_config">
+
<p>
Struts has builtin support for internationalization (I18N).
You can define one or more <code><message-resources></code> elements
@@ -729,6 +744,7 @@
Different bundles can be used simultaneously in your application, the
'key' attribute is used to specify the desired bundle.
</p>
+
<blockquote>
<ul>
<li>
@@ -754,109 +770,135 @@
</ul>
</blockquote>
<p>Example configuration:</p>
- <pre>
- <message-resources
- parameter="MyWebAppResources"
- null="false" />
- </pre>
+<pre>
+<message-resources
+parameter="MyWebAppResources"
+null="false" />
+</pre>
+
<p>
This would set up a message resource bundle provided in the file
<code>MyWebAppResources.properties</code> under the default key.
Missing resource keys would be displayed as '<i>???keyname???</i>'.
</p>
+
</section>
<section name="4.6.4 PlugIn Configuration" href="plugin_config">
+
<p>
Struts PlugIns are configured using the <code><plug-in></code> element within
the Struts configuration file. This element has only one valid attribute,
'className', which is the fully qualified name of the Java class which
implements the <code>org.apache.struts.action.PlugIn</code> interface.
- </p>
+ </p>
+
<p>
For PlugIns that require configuration themselves, the nested
<code><set-property></code> element is available.
- </p>
- <p>
- This is an example using the Tiles plugin:<br/>
- <pre>
- <plug-in className="org.apache.struts.tiles.TilesPlugin" >
- <set-property property="definitions-config" value="/WEB-INF/tiles-defs.xml"/>
- </plug-in>
- </pre>
- </p>
+ </p>
+
+ <p>
+ This is an example using the Tiles plugin:
+ </p>
+
+<pre>
+<plug-in className="org.apache.struts.tiles.TilesPlugin" >
+<set-property
+ property="definitions-config"
+ value="/WEB-INF/tiles-defs.xml"/>
+</plug-in>
+</pre>
+
</section>
<section name="4.6.5 Other Configuration Objects" href="other_config">
<p>
- Besides the objects related to defining ActionMappings, the Struts configuration may
- contain elements that create other useful objects.
+ Besides the objects related to defining ActionMappings, the Struts configuration may
+ contain elements that create other useful objects.
</p>
<p>
- The <code><data-sources></code> section, which
- specifies data sources that your application can use.This is how you would specify a basic data source for your application inside
- of struts-config.xml:
- </p>
-
- <pre>
- <struts-config>
- <data-sources>
- <!-- configuration for GenericDataSource wrapper -->
- <data-source>
- <set-property property="autoCommit"
- value="false"/>
- <set-property property="description"
- value="Example Data Source Configuration"/>
- <set-property property="driverClass"
- value="org.postgresql.Driver"/>
- <set-property property="maxCount"
- value="4"/>
- <set-property property="minCount"
- value="2"/>
- <set-property property="password"
- value="mypassword"/>
- <set-property property="url"
- value="jdbc:postgresql://localhost/mydatabase"/>
- <set-property property="user"
- value="myusername"/>
- </data-source>
-
- <!-- configuration for commons BasicDataSource -->
- <data-source type="org.apache.commons.dbcp.BasicDataSource">
- <set-property property="driverClassName"
- value="org.postgresql.Driver" />
- <set-property property="url"
- value="jdbc:postgresql://localhost/mydatabase" />
- <set-property property="maxActive"
- value="10" />
- <set-property property="maxWait"
- value="5000" />
- <set-property property="defaultAutoCommit"
- value="false" />
- <set-property property="defaultReadOnly"
- value="false" />
-
- </data-source>
- </data-sources>
- </struts-config>
- </pre>
-
- <p>
- For information on how to retrieve the data source, see the
- <a href="building_model.html#databases">Accessing Relational Databases</a> section.
- </p>
- <p>
- <i>Note: Since Struts is now using commons-dbcp for all it's
- data-source needs, the query you provide for the pingQuery
- attribute must return at least one row.</i><br/>
- <br/>
- <b>Example:</b> <code>SELECT COUNT(*) FROM VALIDTABLE</code><br/>
- <br/>
- Just be sure you to replace "VALIDTABLE" with the name of a valid table in your database.
+ The <code><data-sources></code> section, which specifies data sources that your application can use.
+ This is how you would specify a basic data source for your application inside of struts-config.xml:
</p>
+<pre><![CDATA[
+<struts-config>
+<data-sources>
+<!-- configuration for GenericDataSource wrapper -->
+<data-source>
+ <set-property
+ property="autoCommit"
+ value="false"/>
+ <set-property
+ property="description"
+ value="Example Data Source Configuration"/>
+ <set-property
+ property="driverClass"
+ value="org.postgresql.Driver"/>
+ <set-property
+ property="maxCount"
+ value="4"/>
+ <set-property
+ property="minCount"
+ value="2"/>
+ <set-property
+ property="password"
+ value="mypassword"/>
+ <set-property
+ property="url"
+ value="jdbc:postgresql://localhost/mydatabase"/>
+ <set-property
+ property="user"
+ value="myusername"/>
+</data-source>
+
+<!-- configuration for commons BasicDataSource -->
+<data-source type="org.apache.commons.dbcp.BasicDataSource">
+ <set-property
+ property="driverClassName"
+ value="org.postgresql.Driver" />
+ <set-property
+ property="url"
+ value="jdbc:postgresql://localhost/mydatabase" />
+ <set-property
+ property="maxActive"
+ value="10" />
+ <set-property
+ property="maxWait"
+ value="5000" />
+ <set-property
+ property="defaultAutoCommit"
+ value="false" />
+ <set-property
+ property="defaultReadOnly"
+ value="false" />
+
+</data-source>
+</data-sources>
+</struts-config>
+]]></pre>
+
+ <p>
+ For information on how to retrieve the data source, see the
+ <a href="building_model.html#databases">Accessing Relational Databases</a> section.
+ </p>
+
+ <p>
+ <i>Note: Since Struts is now using commons-dbcp for all it's
+ data-source needs, the query you provide for the pingQuery
+ attribute must return at least one row.</i>
+ </p>
+
+ <p>
+ <b>Example:</b> <code>SELECT COUNT(*) FROM VALIDTABLE</code>
+ </p>
+
+ <p>
+ Just be sure you to replace "VALIDTABLE" with the name of a valid table in your database.
+ </p>
</section>
@@ -874,42 +916,40 @@
<p>
Add an entry defining the action servlet itself, along with the appropriate
- initialization parameters. Such an entry might look like this:
- </p>
- <p>
- [:TODO: Conform with MailReader example application]
+ initialization parameters. Such an entry might look like this:
</p>
-<pre>
-<servlet>
- <servlet-name>action</servlet-name>
- <servlet-class>
+
+<pre><![CDATA[
+<servlet>
+ <servlet-name>action</servlet-name>
+ <servlet-class>
org.apache.struts.action.ActionServlet
- </servlet-class>
- <init-param>
- <param-name>application</param-name>
- <param-value>
+ </servlet-class>
+ <init-param>
+ <param-name>application</param-name>
+ <param-value>
org.apache.struts.example.ApplicationResources
- </param-value>
- </init-param>
- <init-param>
- <param-name>config</param-name>
- <param-value>
+ </param-value>
+ </init-param>
+ <init-param>
+ <param-name>config</param-name>
+ <param-value>
/WEB-INF/struts-config.xml
- </param-value>
- </init-param>
- <init-param>
- <param-name>debug</param-name>
- <param-value>2</param-value>
- </init-param>
- <init-param>
- <param-name>mapping</param-name>
- <param-value>
+ </param-value>
+ </init-param>
+ <init-param>
+ <param-name>debug</param-name>
+ <param-value>2</param-value>
+ </init-param>
+ <init-param>
+ <param-name>mapping</param-name>
+ <param-value>
org.apache.struts.example.ApplicationMapping
- </param-value>
- </init-param>
- <load-on-startup>2</load-on-startup>
-</servlet>
-</pre>
+ </param-value>
+ </init-param>
+ <load-on-startup>2</load-on-startup>
+</servlet>
+]]></pre>
<p>
The initialization parameters supported by the controller servlet are
@@ -918,7 +958,8 @@
describe the default values that are assumed if you do not provide a value for
that initialization parameter.
</p>
- <ul>
+
+ <ul>
<li><strong>config</strong> - Context-relative path to the XML resource
containing the configuration information for the default module.
[/WEB-INF/struts-config.xml].</li>
@@ -1256,28 +1297,30 @@
of your module (this gets used when determining which URIs fall under a
given module, so choose something meaningful!). For example:
</p>
- <pre>
- ...
- <init-param>
- <param-name>config</param-name>
- <param-value>/WEB-INF/conf/struts-default.xml</param-value>
- </init-param>
- <init-param>
- <param-name>config/module1</param-name>
- <param-value>/WEB-INF/conf/struts-module1.xml</param-value>
- </init-param>
- ...
- </pre>
+<pre>
+ ...
+ <init-param>
+ <param-name>config</param-name>
+ <param-value>/WEB-INF/conf/struts-default.xml</param-value>
+ </init-param>
+ <init-param>
+ <param-name>config/module1</param-name>
+ <param-value>/WEB-INF/conf/struts-module1.xml</param-value>
+ </init-param>
+ ...
+</pre>
<p>
This says I have two modules. One happens to be the "default" module,
which has no "/module" in it's name, and one named "module1" (config/module1). I've told
the controller it can find their respective configurations under /WEB-INF/conf (which is
where I put all my configuration files). Pretty simple!
</p>
+
<p>
(My struts-default.xml would be equivalent to what most folks call struts-config.xml. I just
like the symmety of having all my Struts module files being named struts-<module>.xml)
</p>
+
</section>
<section name="4.7.4.3 Using Actions for Pages" href="module_config-use_actions">
@@ -1291,9 +1334,9 @@
<p>
The simplest way to do this is to use the <code>forward</code> property of the ActionMapping:
</p>
- <pre>
- <action path="/view" forward="/view.jsp"/>
- </pre>
+<pre>
+<action path="/view" forward="/view.jsp"/>
+</pre>
</section>
<section name="4.7.4.4 Switching Modules" href="module_config-switching">
@@ -1307,57 +1350,59 @@
Here's an example of a global forward:
</p>
<p>
- <pre>
- ...
- <struts-config>
- ...
- <global-forwards>
- <forward name="toModuleB"
- contextRelative="true"
- path="/moduleB/index.do"
- redirect="true"/>
- ...
- </global-forwards>
- ...
- </struts-config>
- </pre>
+<pre>
+ ...
+ <struts-config>
+ ...
+ <global-forwards>
+ <forward name="toModuleB"
+ contextRelative="true"
+ path="/moduleB/index.do"
+ redirect="true"/>
+ ...
+ </global-forwards>
+ ...
+ </struts-config>
+ </pre>
</p>
<p>
You could do the same thing with a local forward declared in an
ActionMapping:
</p>
<p>
- <pre>
- ...
- <struts-config>
- ...
- <action-mappings>
- ...
- <action ... >
- <forward name="success"
- contextRelative="true"
- path="/moduleB/index.do"
- redirect="true"/>
- </action>
- ...
- </action-mappingss>
- ...
- </struts-config>
- </pre>
+<pre>
+ ...
+ <struts-config>
+ ...
+ <action-mappings>
+ ...
+ <action ... >
+ <forward name="success"
+ contextRelative="true"
+ path="/moduleB/index.do"
+ redirect="true"/>
+ </action>
+ ...
+ </action-mappingss>
+ ...
+ </struts-config>
+ </pre>
</p>
<p>
Finally, you could use <code>org.apache.struts.actions.SwitchAction
</code>, like so:
</p>
<p>
- ...
- <action-mappings>
- <action path="/toModule"
- type="org.apache.struts.actions.SwitchAction"/>
- ...
- </action-mappingss>
- ...
- </p>
+ <pre>
+...
+<action-mappings>
+<action path="/toModule"
+ type="org.apache.struts.actions.SwitchAction"/>
+...
+</action-mappingss>
+...
+</pre>
+ </p>
<p>
Now, to change to ModuleB, we would use a URI like this:
</p>
@@ -1428,26 +1473,26 @@
are two imports and a declaration for a logger. Let's take a look:
</p>
<p>
- <pre>
- package com.foo;
- ...
- import org.apache.commons.logging.Log;
- import org.apache.commons.logging.LogFactory;
- ...
- public class Foo {
- ...
- private static Log log = LogFactory.getLog(Foo.class);
- ...
- public void setBar(Bar bar)
- {
- if (log.isTraceEnabled())
- log.trace("Setting bar to " + bar);
-
- this.bar = bar;
- }
- ...
- }
- </pre>
+<pre>
+ package com.foo;
+ ...
+ import org.apache.commons.logging.Log;
+ import org.apache.commons.logging.LogFactory;
+ ...
+ public class Foo {
+ ...
+ private static Log log = LogFactory.getLog(Foo.class);
+ ...
+ public void setBar(Bar bar)
+ {
+ if (log.isTraceEnabled())
+ log.trace("Setting bar to " + bar);
+
+ this.bar = bar;
+ }
+ ...
+ }
+</pre>
</p>
<p>
The general idea is to instantiate a single logger per class and to
1.3 +3 -3 jakarta-struts/doc/userGuide/building_apps.xml
Index: building_apps.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/building_apps.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- building_apps.xml 10 Oct 2002 03:42:45 -0000 1.2
+++ building_apps.xml 30 Nov 2002 14:30:27 -0000 1.3
@@ -87,9 +87,9 @@
<a href="http://husted.com/struts/tips/002.html">(more...)</a></li>
<li>Use the <code>execute</code> method (or its surrogates) of your
Action class to interface with objects in your application responsible
- for database interaction, such as EJBs, etc. [:TODO: find good doc to link to]</li>
+ for database interaction, such as EJBs, etc. <!-- [:TODO: find good doc to link to] --></li>
<li>Use the return value of the <code>execute</code> method (or its surrogates)
- direct the user interface to the appropriate next page. [:TODO: find good doc to link to]</li>
+ direct the user interface to the appropriate next page. <!-- [:TODO: find good doc to link to] --></li>
</ol>
<li>Create <code>struts-config.xml</code> to associate forms with
actions. The file minimally needs:</li>
@@ -131,7 +131,7 @@
<li>Deployment</li>
<ol>
<li>Build script should create a war file containing the files developed
- above, along with files that make up the Struts framework. [:TODO: describe this
+ above, along with files that make up the Struts framework. <!-- [:TODO: describe this -->
further, look for doc to link to]</li>
</ol>
</ol>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>