craigmcc 2002/07/27 19:25:58
Modified: doc/userGuide index.xml preface.xml
Log:
Check in a bunch more pointers to further information, and start filling
out the sections on servlet topics.
Revision Changes Path
1.13 +10 -8 jakarta-struts/doc/userGuide/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/index.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- index.xml 5 Jul 2002 15:55:48 -0000 1.12
+++ index.xml 28 Jul 2002 02:25:58 -0000 1.13
@@ -18,14 +18,16 @@
<ul>
<li><a href="preface.html">0. Preface</a>
<ul>
- <li><a href="preface.html#http">HTTP, HTML, and User Agents</a></li>
- <li><a href="preface.html#cycle">The HTTP Request/Response
Cycle</a></li>
- <li><a href="preface.html#java">The Java Language and Application
Frameworks</a></li>
- <li><a href="preface.html#javabeans">JavaBeans</a></li>
- <li><a href="preface.html#resources">Properties files and
ResourceBundles</a></li>
- <li><a href="preface.html#servlets">Java Servlets</a></li>
- <li><a href="preface.html#jsp">JavaServer Pages and JSP Tag
Libraries</a></li>
- <li><a href="preface.html#xml">Extensible Markup Language</a></li>
+ <li><a href="preface.html#suspects">0.1 The Usual Suspects</a></li>
+ <li><a href="preface.html#http">0.2 HTTP, HTML, and User
Agents</a></li>
+ <li><a href="preface.html#cycle">0.3 The HTTP Request/Response
Cycle</a></li>
+ <li><a href="preface.html#java">0.4 The Java Language and Application
Frameworks</a></li>
+ <li><a href="preface.html#javabeans">0.5 JavaBeans</a></li>
+ <li><a href="preface.html#resources">0.6 Properties Files and
ResourceBundles</a></li>
+ <li><a href="preface.html#servlets">0.7 Java Servlets</a></li>
+ <li><a href="preface.html#jsp">0.8 JavaServer Pages and JSP Tag
Libraries</a></li>
+ <li><a href="preface.html#xml">0.9 Extensible Markup Language</a></li>
+ <li><a href="preface.html#jaas">0.10 JAAS</a></li>
</ul></li>
1.6 +327 -32 jakarta-struts/doc/userGuide/preface.xml
Index: preface.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/preface.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- preface.xml 12 Jul 2002 03:59:32 -0000 1.5
+++ preface.xml 28 Jul 2002 02:25:58 -0000 1.6
@@ -11,7 +11,7 @@
<chapter name="0. Preface: Core Technologies">
- <section name="0.1 The Usual Suspects" href="prereqs">
+ <section name="0.1 The Usual Suspects" href="suspects">
<p>
This User Guide is written for active web developers and assumes a working
@@ -24,7 +24,7 @@
<li><a href="#cycle">The HTTP Request/Response Cycle</a></li>
<li><a href="#java">The Java Language and Application Frameworks</a></li>
<li><a href="#javabeans">JavaBeans</a></li>
- <li><a href="#resources">Properties files and ResourceBundles</a></li>
+ <li><a href="#resources">Properties Files and ResourceBundles</a></li>
<li><a href="#servlets">Java Servlets</a></li>
<li><a href="#jsp">JavaServer Pages and JSP Tag Libraries</a></li>
<li><a href="#xml">Extensible Markup Language</a></li>
@@ -72,6 +72,12 @@
<li><a href="http://www.w3.org/MarkUp/Guide/";><b>Getting started with
HTML</b></a> by Dave Raggett</li>
<li><a
href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/HTTP.html#63796";>
<b>HTTP Overview</b></a> in the Java Web Services Tutorial.</li>
+ <li><a href="http://www.rfc-editor.org/rfc/rfc2616.txt";><strong>HTTP/1.1
+ </strong></a> Specification</li>
+ <li><a href="http://www.rfc-editor.org/rfc/rfc2617.txt";><strong>HTTP
+ Basic and Digest Authentication</strong></a> Specification</li>
+ <li><a href="http://www.rfc-editor.org/rfc/rfc2109.txt";><strong>State
+ Management Mechanism</strong></a> Specification (Cookies)</li>
</ul>
</section>
@@ -94,14 +100,20 @@
<p>Struts is written in the popular and versatile
<a href="http://java.sun.com/docs/books/jls/first_edition/html/index.html";>Java
programming language</a>.
- Java is an object-orientated language, and Struts makes good use of many
object-orientated techniques.
- A good understanding of Java, and especially object-orientated programming
(OOP) will help
+ Java is an object-orientated language, and Struts makes good use of many
+ object-orientated techniques. In addition, Java natively supports the
+ concept of <em>threads</em>, which allows more than one task to be
+ performed at the same time. A good understanding of Java, and especially
+ object-orientated programming (OOP) and threading, will help
you get the most out of Struts and this User Guide. </p>
- <p>For more about Java and OOP, see </p>
+ <p>For more about Java and threads, see </p>
<ul>
<li><a
href="http://java.sun.com/docs/books/tutorial/java/index.html";><b>Learning the Java
Language</b></a> in the Java Tutorial</li>
+ <li><a
href="http://java.sun.com/docs/books/tutorial/essentials/threads/index.html";>
+ <b>Threads: Doing Two or More Tasks At Once</b></a> in the Java Language
+ Tutorial</li>
</ul>
<p>Even if you have worked with Java and OOP before, it can also help to be
aware of the
@@ -134,31 +146,39 @@
<p>For more about JavaBeans, see</p>
<ul>
- <li><a
href="http://java.sun.com/docs/books/tutorial/javabeans/index.html";><b>The JavaBean
Trail</b></a> in the Java Tutorial</li>
- <li><a
href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/JSPBeans.html";><b>JavaBeans
Components in JSP Pages</b></a> in the Java Web Services Tutorial</li>
+ <li><a href="http://java.sun.com/products/javabeans/docs/";><strong>The
+ JavaBeans Component Architecture Documentation</strong></a> page at
+ <code>java.sun.com</code>, including a link to download the
+ <a href="http://java.sun.com/products/javabeans/docs/spec.html";>
+ JavaBeans 1.01 Specification</a></li>
+ <li><a href="http://java.sun.com/docs/books/tutorial/javabeans/index.html";>
+ <b>The JavaBean Trail</b></a> in the Java Tutorial</li>
+ <li><a
href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/JSPBeans.html";>
+ <b>JavaBeans Components in JSP Pages</b></a> in the Java Web Services
Tutorial
+ </li>
</ul>
- </section>
+ <section name="0.5.1 Reflection" href="reflection">
- <section name="0.5.1 Reflection" href="reflection">
+ <p>[:TODO:]</p>
- <p>[:TODO:]</p>
+ </section>
- </section>
+ <section name="0.5.2 Maps" href="Maps">
- <section name="0.5.2 Maps" href="Maps">
+ <p>[:TODO:]</p>
- <p>[:TODO:]</p>
+ </section>
- </section>
+ <section name="0.5.3 DynaBeans" href="dynabeans">
- <section name="0.5.3 DynaBeans" href="dynabeans">
+ <p>[:TODO:]</p>
- <p>[:TODO:]</p>
+ </section>
</section>
- <section name="0.6 Properties files and ResourceBundles" href="resources">
+ <section name="0.6 Properties Files and ResourceBundles" href="resources">
<p>Java applications, including web applications, are often configured using
<a
href="http://java.sun.com/j2se/1.4.1/docs/api/java/util/Properties.html";>Properties</a>
@@ -201,21 +221,290 @@
<p>For more about Java Servlets, see </p>
<ul>
- <li><a href=""><b>Java Servlet Technology</b></a> in the Java Web
- Services Tutorial.</li>
+ <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 name="0.7.1 Servlets" href="servlets">
- <section name="0.7.1 Java Servlet Contexts" href="contexts">
+ <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
+ before any request is processed.</li>
+ <li><strong>public void doGet(HttpServletRequest request,
+ HttpServletResponse response)</strong> - Called to process a
+ specific request received using the HTTP <code>GET</code> protocol,
+ which generates a corresponding dynamic response.</li>
+ <li><strong>public void doPost(HttpServletRequest request,
+ HttpServletResponse response)</strong> - Called to process a
+ specific request received using the HTTP <code>POST</code> protocol,
+ which generates a corresponding dynamic response.</li>
+ <li><strong>public void destroy()</strong> - Called by the servlet
+ container when it takes this servlet instance out of service,
+ such as when a web application is being undeployed or when the
+ entire container is being shut down.</li>
+ </ul>
+
+ <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>
+
+ </section>
+
+ <section name="0.7.2 Servlet Context" href="context">
+
+ <p>The <em>ServletContext</em> interface 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.
+ Servlet contexts provide several APIs that are very useful in building
+ Struts based web applications:</p>
+ <ul>
+ <li><em>Access To Web Application Resources</em> - A servlet can
+ access static resource files within the web application using the
+ <code>getResource()</code> and <code>getResourceAsStream()</code>
+ methods.</li>
+ <li><em>Servlet Context Attributes</em> - The context makes available
+ a storage place for Java objects, identified by string-valued keys.
+ These attributes are global to the entire web application, and may
+ be accessed by a servlet using the <code>getAttribute()</code>,
+ <code>getAttributeNames()</code>, <code>removeAttribute()</code>, and
+ <code>setAttribute()</code> methods. From a JSP page, servlet
+ context attributes are also known as "application scope beans".
+ </li>
+ </ul>
+
+ <p>See the Javadocs for <code>javax.servlet.ServletContext</code>
+ for more information.</p>
+
+ </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
+ 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
+ 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
+ of the request (POST only) are available by name.</li>
+ <li><em>Request Characteristics</em> - Many other characteristics
+ of the incoming HTTP request, such as the method used (normally
+ GET or POST) the protocol scheme used ("http" or "https"), and
+ similar values.</li>
+ <li><em>Request URI Information</em> - The original request URI
+ being processed is available via <code>getRequestURI()</code>.
+ In addition, the constituent parts into which the servlet container
+ parses the request URI (contextPath, servletPath, and pathInfo) are
+ available separately.</li>
+ <li><em>User Information</em> - If you are using
+ <a href="#security">Container Managed Security</a>, you can ask
+ the username of the authenticated user, retrieve a
+ <code>Principal</code> object representing the current user, and
+ whether the current user is authorized for a specified role.</li>
+ </ul>
+
+ <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
+ 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
+ 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>
+
+ </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>
+ <ul>
+ <li><em>Set Headers</em> - You can set HTTP headers that will be
+ included in the response. The most important header is the
+ <code>Content-Type</code> header, which tells your client what
+ kind of information is included in the body of this response.
+ This is typically set to <code>text/html</code> for an HTML page,
+ or <code>text/xml</code> for an XML document.</li>
+ <li><em>Set Cookies</em> - You can add cookies to the current
+ response.</li>
+ <li><em>Send Error Responses</em> - You can send an HTTP error status
+ (instead of a usual page of content) using
+ <code>sendError()</code>.</li>
+ <li><em>Redirect To Another Resource</em> - You can use the
+ <code>sendRedirect()</code> method to redirect the client to
+ some other URL that you specify.</li>
+ </ul>
+
+ <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
+ 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>
+
+ </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
+ let you compose a set of components that will process a request or
+ 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
+ called).</p>
+
+ <p>Struts 1.0 and 1.1 require only version 2.2 or later of the
+ Servlet Specification to be implemented by your servlet container,
+ so Struts does not itself utilize Filters at this time. However,
+ you can still use them yourself if you are running on a 2.3 or later
+ 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>See the Javadocs for <code>javax.servlet.Filter</code> for more
+ information.</p>
+
+ </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
+ HTTP that identifies a subsequent request from the same user as being
+ 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>
+
+ <p>To alleviate this difficulty, the servlet API provides a programmatic
+ concept called a <em>session</em>, represented as an object that
+ implements the <code>javax.servlet.http.HttpSession</code> interface.
+ The servlet container will use one of two techniques (cookies or
+ 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
+ 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
+ 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>
+
+ <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 two 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
+ an impact on the number of simultaneous users that your application can
+ 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>
+
+ </section>
+
+ <section name="0.7.7 Dispatching Requests" href="dispatch">
+
+ <p>[:TODO:]</p>
+
+ </section>
+
+ <section name="0.7.8 Web Applications" href="webapp">
+
+ <p>[:TODO:]</p>
+
+ </section>
+
+ <section name="0.7.9 Application Lifecycle Events" href="events">
+
+ <p>[:TODO:]</p>
+
+ </section>
+
+ <section name="0.7.10 Security" href="security">
+
+ <p>[:TODO:]</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>
+ </ul>
- <p>[:TODO:]</p>
-
- </section>
-
- <section name="0.7.2 Java Servlet Forwards" href="forwards">
-
- <p>[:TODO:]</p>
+ </section>
</section>
@@ -235,6 +524,12 @@
<p>For more about JavaServerPages and JSP Tag Libraries see </p>
<ul>
+ <li><a href="http://java.sun.com/products/jsp/";><strong>The
+ JavaServer Pages Technology</strong></a> page at
+ <code>java.sun.com</code></li>
+ <li><a href="http://java.sun.com/products/jsp/download/";><strong>The
+ JSP 1.1 and 1.2 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/JSPIntro.html";><b>JavaServer
Pages Technology</b></a> in the Java Web Services Tutorial</li>
<li><a
href="http://java.sun.com/webservices/docs/1.0/tutorial/doc/JSPTags.html";><b>Custom
Tags in JSP Pages</b></a> in the Java Web Services Tutorial</li>
</ul>
@@ -277,17 +572,17 @@
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 name="0.9.1 Descriptors" href="descriptors">
+ <section name="0.9.1 Descriptors" href="descriptors">
- <p>[:TODO:]</p>
+ <p>[:TODO:]</p>
+
+ </section>
</section>
<section name="0.10 JAAS" href="jaas">
<p>[:TODO:]</p>
-
- </section>
<p align="center">
Next: <a href="introduction.html">Introduction</a>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
