You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by jf...@apache.org on 2002/03/26 15:18:45 UTC
cvs commit: jakarta-tomcat-4.0/webapps/tomcat-docs introduction.xml jndi-resources-howto.xml proxy-howto.xml realm-howto.xml ssl-howto.xml
jfclere 02/03/26 06:18:45
Modified: catalina/docs Tag: tomcat_40_branch JDBCRealm-howto.html
JDBCStore-howto.html
catalina/etc Tag: tomcat_40_branch bootstrap.MF
catalina/src/share/org/apache/catalina/cluster Tag:
tomcat_40_branch LocalStrings.properties
catalina/src/share/org/apache/naming Tag: tomcat_40_branch
LocalStrings.properties
jasper/doc/dev Tag: tomcat_40_branch
ModifsForPropertyEditor.html TODO.html status.html
service/native Tag: tomcat_40_branch signals.c
tester/src/tester/org/apache/tester Tag: tomcat_40_branch
Xerces01.java
tester/web Tag: tomcat_40_branch Xerces01.xml includeme.txt
tester/web/WEB-INF/cgi Tag: tomcat_40_branch array.pl
binary.pl concat.pl dowhile.pl else.pl elsif.pl
exponents.pl for.pl getday.pl if.pl increment.pl
modifyall.pl preference.pl subparseform.lib
subroutines.lib test-cgi.pl
tester/web/golden Tag: tomcat_40_branch Encoding01.txt
Encoding02.txt Encoding03.txt Include06.txt
JspDoc01.txt array.txt binary.txt days.txt
dowhile.txt exponents.txt getday.txt increment.txt
modifyall.txt preference.txt
tester/web/ssidir Tag: tomcat_40_branch includeme.txt
webapps/examples/WEB-INF/classes/compressionFilters Tag:
tomcat_40_branch CompressionFilter.java
CompressionFilterTestServlet.java
webapps/examples/jsp/forward Tag: tomcat_40_branch one.jsp
two.html
webapps/examples/jsp/jsptoserv Tag: tomcat_40_branch
hello.jsp jsptoservlet.jsp jts.txt
webapps/tomcat-docs Tag: tomcat_40_branch introduction.xml
jndi-resources-howto.xml proxy-howto.xml
realm-howto.xml ssl-howto.xml
Log:
Arrange CR/LF and missing LF (noeol). (no other changes)
Revision Changes Path
No revision
No revision
1.4.2.1 +2 -2 jakarta-tomcat-4.0/catalina/docs/Attic/JDBCRealm-howto.html
Index: JDBCRealm-howto.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/docs/Attic/JDBCRealm-howto.html,v
retrieving revision 1.4
retrieving revision 1.4.2.1
diff -u -r1.4 -r1.4.2.1
--- JDBCRealm-howto.html 22 May 2001 20:47:05 -0000 1.4
+++ JDBCRealm-howto.html 26 Mar 2002 14:18:42 -0000 1.4.2.1
@@ -234,7 +234,7 @@
- Make sure that the JDBC driver is in the lib directory.
<br>
- If you have problem connecting you can specify connectionName and connectionPassword</p>
-<div align="center">$Header: /home/cvs/jakarta-tomcat-4.0/catalina/docs/Attic/JDBCRealm-howto.html,v 1.4 2001/05/22 20:47:05 bip Exp $
+<div align="center">$Header: /home/cvs/jakarta-tomcat-4.0/catalina/docs/Attic/JDBCRealm-howto.html,v 1.4.2.1 2002/03/26 14:18:42 jfclere Exp $
</div>
</body>
-</html>
\ No newline at end of file
+</html>
1.1.2.1 +2 -2 jakarta-tomcat-4.0/catalina/docs/JDBCStore-howto.html
Index: JDBCStore-howto.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/docs/JDBCStore-howto.html,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- JDBCStore-howto.html 27 Apr 2001 22:11:03 -0000 1.1
+++ JDBCStore-howto.html 26 Mar 2002 14:18:42 -0000 1.1.2.1
@@ -191,7 +191,7 @@
</tr>
</table>
<p> </p>
-<div align="center">$Header: /home/cvs/jakarta-tomcat-4.0/catalina/docs/JDBCStore-howto.html,v 1.1 2001/04/27 22:11:03 bip Exp $
+<div align="center">$Header: /home/cvs/jakarta-tomcat-4.0/catalina/docs/JDBCStore-howto.html,v 1.1.2.1 2002/03/26 14:18:42 jfclere Exp $
</div>
</body>
-</html>
\ No newline at end of file
+</html>
No revision
No revision
1.1.2.1 +1 -1 jakarta-tomcat-4.0/catalina/etc/bootstrap.MF
Index: bootstrap.MF
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/etc/bootstrap.MF,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- bootstrap.MF 16 Jul 2001 06:57:09 -0000 1.1
+++ bootstrap.MF 26 Mar 2002 14:18:42 -0000 1.1.2.1
@@ -1,4 +1,4 @@
Manifest-Version: 1.0
Main-Class: org.apache.catalina.startup.Bootstrap
Specification-Title: Catalina
-Specification-Version: 1.0
\ No newline at end of file
+Specification-Version: 1.0
No revision
No revision
1.1.2.2 +1 -1 jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/cluster/LocalStrings.properties
Index: LocalStrings.properties
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/cluster/LocalStrings.properties,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- LocalStrings.properties 3 Jan 2002 10:44:32 -0000 1.1.2.1
+++ LocalStrings.properties 26 Mar 2002 14:18:42 -0000 1.1.2.2
@@ -8,4 +8,4 @@
standardCluster.invalidAddress=Invalid multicastAddress {0}
standardCluster.joinException=An error occurred when trying to join group {0}
standardCluster.leaveException=An error occurred when trying to leave group {0}
-multicastSender.sendException=An error occurred when trying to replicate {0}
\ No newline at end of file
+multicastSender.sendException=An error occurred when trying to replicate {0}
No revision
No revision
1.2.4.1 +1 -1 jakarta-tomcat-4.0/catalina/src/share/org/apache/naming/LocalStrings.properties
Index: LocalStrings.properties
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/naming/LocalStrings.properties,v
retrieving revision 1.2
retrieving revision 1.2.4.1
diff -u -r1.2 -r1.2.4.1
--- LocalStrings.properties 11 Nov 2000 01:47:47 -0000 1.2
+++ LocalStrings.properties 26 Mar 2002 14:18:42 -0000 1.2.4.1
@@ -7,4 +7,4 @@
namingContext.readOnly=Context is read only
namingContext.invalidName=Name is not valid
namingContext.alreadyBound=Name {0} is already bound in this Context
-namingContext.noAbsoluteName=Can't generate an absolute name for this namespace
\ No newline at end of file
+namingContext.noAbsoluteName=Can't generate an absolute name for this namespace
No revision
No revision
1.1.4.1 +1 -1 jakarta-tomcat-4.0/jasper/doc/dev/ModifsForPropertyEditor.html
Index: ModifsForPropertyEditor.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/jasper/doc/dev/ModifsForPropertyEditor.html,v
retrieving revision 1.1
retrieving revision 1.1.4.1
diff -u -r1.1 -r1.1.4.1
--- ModifsForPropertyEditor.html 26 Sep 2000 17:46:01 -0000 1.1
+++ ModifsForPropertyEditor.html 26 Mar 2002 14:18:42 -0000 1.1.4.1
@@ -108,4 +108,4 @@
Should it?
-- Pierre
-</pre>
\ No newline at end of file
+</pre>
1.6.4.1 +1 -1 jakarta-tomcat-4.0/jasper/doc/dev/TODO.html
Index: TODO.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/jasper/doc/dev/TODO.html,v
retrieving revision 1.6
retrieving revision 1.6.4.1
diff -u -r1.6 -r1.6.4.1
--- TODO.html 17 Oct 2000 23:00:10 -0000 1.6
+++ TODO.html 26 Mar 2002 14:18:42 -0000 1.6.4.1
@@ -124,4 +124,4 @@
Just as for Tomcat bugs, RFEs are currently tracked at <a href="http://znutar.cortexity.com:8888/BugRatViewer">http://znutar.cortexity.com:8888/BugRatViewer</a>.
</body>
-</html>
\ No newline at end of file
+</html>
1.6.4.1 +2 -2 jakarta-tomcat-4.0/jasper/doc/dev/status.html
Index: status.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/jasper/doc/dev/status.html,v
retrieving revision 1.6
retrieving revision 1.6.4.1
diff -u -r1.6 -r1.6.4.1
--- status.html 17 Oct 2000 23:00:10 -0000 1.6
+++ status.html 26 Mar 2002 14:18:42 -0000 1.6.4.1
@@ -8,7 +8,7 @@
<h1>Status of Jasper</h1>
The goal of this document is to keep everyone informed of the major developments
happening with Jasper.<br>
-<i>$Id: status.html,v 1.6 2000/10/17 23:00:10 pierred Exp $</i>
+<i>$Id: status.html,v 1.6.4.1 2002/03/26 14:18:42 jfclere Exp $</i>
<h2>Current Status</h2>
Trying to bootstrap the work required to bring Jasper in compliance
@@ -64,4 +64,4 @@
needs to be done. Check the <a href="README.html">README</a>.<p>
<li>2000/08/25<br>
-One of the goals of the new architecture of Jasper is to be independent of the servlet engine. This is why jasper now stands in its own directory in tomcat-4.0. It currently works with Catalina, with only a few dependencies, which we will work on removing. Please check the document <a href="jasper-independent.html">Jasper as an Independent Component</a> for the story.
\ No newline at end of file
+One of the goals of the new architecture of Jasper is to be independent of the servlet engine. This is why jasper now stands in its own directory in tomcat-4.0. It currently works with Catalina, with only a few dependencies, which we will work on removing. Please check the document <a href="jasper-independent.html">Jasper as an Independent Component</a> for the story.
No revision
No revision
1.1.2.1 +82 -82 jakarta-tomcat-4.0/service/native/Attic/signals.c
Index: signals.c
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/service/native/Attic/signals.c,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- signals.c 8 Aug 2001 22:46:32 -0000 1.1
+++ signals.c 26 Mar 2002 14:18:42 -0000 1.1.2.1
@@ -1,82 +1,82 @@
-/*
- * as Windows does not support signal, OnServe use event to emulate them.
- * The supported signal is SIGTERM.
- * The kills.c contains the kill logic.
- */
-#ifdef OS_CYGWIN
-#include <windows.h>
-#include <stdio.h>
-static void (*HandleTerm)()=NULL; // address of the handler routine.
-
-/*
- * Event handling routine
- */
-void v_difthf(LPVOID par)
-{
-HANDLE hevint; /* make a local copy because the parameter is shared! */
-
- hevint = (HANDLE) par;
-
- for (;;) {
- if (WaitForSingleObject(hevint,INFINITE) == WAIT_FAILED) {
- // something have gone wrong.
- return; // may be something more is needed.
- }
-
- // call the interrupt handler.
- if (HandleTerm==NULL) return;
- HandleTerm();
- }
-}
-
-/*
- * set a routine handler for the signal
- * note that it cannot be used to change the signal handler
- */
-int SetTerm(void (*func)())
-{
-char Name[256];
-HANDLE hevint, hthread;
-DWORD ThreadId;
-SECURITY_ATTRIBUTES sa;
-SECURITY_DESCRIPTOR sd;
-
- sprintf(Name,"TERM%ld",GetCurrentProcessId());
-
- /*
- * event cannot be inherited.
- * the event is reseted to nonsignaled after the waiting thread is released.
- * the start state is resetted.
- */
-
- // Initialize the new security descriptor.
- InitializeSecurityDescriptor (&sd, SECURITY_DESCRIPTOR_REVISION);
-
- // Add a NULL descriptor ACL to the security descriptor.
- SetSecurityDescriptorDacl (&sd, TRUE, (PACL)NULL, FALSE);
-
- sa.nLength = sizeof(sa);
- sa.lpSecurityDescriptor = &sd;
- sa.bInheritHandle = TRUE;
-
-
- // It works also with NULL instead &sa!!
- hevint = CreateEvent(&sa,FALSE, FALSE,Name);
-
- HandleTerm = (int (*)()) func;
-
- if (hevint == NULL) return(-1); // failed
-
- /* create the thread to wait for event */
- hthread = CreateThread(NULL,0,(LPTHREAD_START_ROUTINE) v_difthf,
- (LPVOID) hevint, 0, &ThreadId);
- if (hthread == NULL) {
- // failed remove the event
- CloseHandle(hevint); // windows will remove it.
- return(-1);
- }
-
- CloseHandle(hthread); // not needed
- return(0);
-}
-#endif
+/*
+ * as Windows does not support signal, OnServe use event to emulate them.
+ * The supported signal is SIGTERM.
+ * The kills.c contains the kill logic.
+ */
+#ifdef OS_CYGWIN
+#include <windows.h>
+#include <stdio.h>
+static void (*HandleTerm)()=NULL; // address of the handler routine.
+
+/*
+ * Event handling routine
+ */
+void v_difthf(LPVOID par)
+{
+HANDLE hevint; /* make a local copy because the parameter is shared! */
+
+ hevint = (HANDLE) par;
+
+ for (;;) {
+ if (WaitForSingleObject(hevint,INFINITE) == WAIT_FAILED) {
+ // something have gone wrong.
+ return; // may be something more is needed.
+ }
+
+ // call the interrupt handler.
+ if (HandleTerm==NULL) return;
+ HandleTerm();
+ }
+}
+
+/*
+ * set a routine handler for the signal
+ * note that it cannot be used to change the signal handler
+ */
+int SetTerm(void (*func)())
+{
+char Name[256];
+HANDLE hevint, hthread;
+DWORD ThreadId;
+SECURITY_ATTRIBUTES sa;
+SECURITY_DESCRIPTOR sd;
+
+ sprintf(Name,"TERM%ld",GetCurrentProcessId());
+
+ /*
+ * event cannot be inherited.
+ * the event is reseted to nonsignaled after the waiting thread is released.
+ * the start state is resetted.
+ */
+
+ // Initialize the new security descriptor.
+ InitializeSecurityDescriptor (&sd, SECURITY_DESCRIPTOR_REVISION);
+
+ // Add a NULL descriptor ACL to the security descriptor.
+ SetSecurityDescriptorDacl (&sd, TRUE, (PACL)NULL, FALSE);
+
+ sa.nLength = sizeof(sa);
+ sa.lpSecurityDescriptor = &sd;
+ sa.bInheritHandle = TRUE;
+
+
+ // It works also with NULL instead &sa!!
+ hevint = CreateEvent(&sa,FALSE, FALSE,Name);
+
+ HandleTerm = (int (*)()) func;
+
+ if (hevint == NULL) return(-1); // failed
+
+ /* create the thread to wait for event */
+ hthread = CreateThread(NULL,0,(LPTHREAD_START_ROUTINE) v_difthf,
+ (LPVOID) hevint, 0, &ThreadId);
+ if (hthread == NULL) {
+ // failed remove the event
+ CloseHandle(hevint); // windows will remove it.
+ return(-1);
+ }
+
+ CloseHandle(hthread); // not needed
+ return(0);
+}
+#endif
No revision
No revision
1.1.4.1 +138 -138 jakarta-tomcat-4.0/tester/src/tester/org/apache/tester/Xerces01.java
Index: Xerces01.java
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/src/tester/org/apache/tester/Xerces01.java,v
retrieving revision 1.1
retrieving revision 1.1.4.1
diff -u -r1.1 -r1.1.4.1
--- Xerces01.java 13 Mar 2001 19:06:17 -0000 1.1
+++ Xerces01.java 26 Mar 2002 14:18:42 -0000 1.1.4.1
@@ -1,138 +1,138 @@
-/* ========================================================================= *
- * *
- * The Apache Software License, Version 1.1 *
- * *
- * Copyright (c) 1999, 2000, 2001 The Apache Software Foundation. *
- * All rights reserved. *
- * *
- * ========================================================================= *
- * *
- * Redistribution and use in source and binary forms, with or without modi- *
- * fication, are permitted provided that the following conditions are met: *
- * *
- * 1. Redistributions of source code must retain the above copyright notice *
- * notice, this list of conditions and the following disclaimer. *
- * *
- * 2. Redistributions in binary form must reproduce the above copyright *
- * notice, this list of conditions and the following disclaimer in the *
- * documentation and/or other materials provided with the distribution. *
- * *
- * 3. The end-user documentation included with the redistribution, if any, *
- * must include the following acknowlegement: *
- * *
- * "This product includes software developed by the Apache Software *
- * Foundation <http://www.apache.org/>." *
- * *
- * Alternately, this acknowlegement may appear in the software itself, if *
- * and wherever such third-party acknowlegements normally appear. *
- * *
- * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software *
- * Foundation" must not be used to endorse or promote products derived *
- * from this software without prior written permission. For written *
- * permission, please contact <ap...@apache.org>. *
- * *
- * 5. Products derived from this software may not be called "Apache" nor may *
- * "Apache" appear in their names without prior written permission of the *
- * Apache Software Foundation. *
- * *
- * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES *
- * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY *
- * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL *
- * THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY *
- * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL *
- * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS *
- * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) *
- * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, *
- * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN *
- * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE *
- * POSSIBILITY OF SUCH DAMAGE. *
- * *
- * ========================================================================= *
- * *
- * This software consists of voluntary contributions made by many indivi- *
- * duals on behalf of the Apache Software Foundation. For more information *
- * on the Apache Software Foundation, please see <http://www.apache.org/>. *
- * *
- * ========================================================================= */
-
-
-package org.apache.tester;
-
-import java.io.IOException;
-import java.io.PrintWriter;
-import java.net.MalformedURLException;
-import java.net.URL;
-import javax.servlet.*;
-import javax.servlet.http.*;
-
-
-/**
- * Ensure that we can use the Xerces parser while included in a web application
- * even though the servlet container might utilize its own parser for internal
- * use.
- *
- * @author Amy Roh
- * @author Craig McClanahan
- * @version $Revision: 1.1 $ $Date: 2001/03/13 19:06:17 $
- */
-
-public class Xerces01 extends HttpServlet {
-
-
- // --------------------------------------------------------- Public Methods
-
-
- /**
- * Perform a simple SAX parse using Xerces (based on the SAXCount
- * example application).
- *
- * @param request The servlet request we are processing
- * @param response The servlet response we are creating
- *
- * @exception IOException if an input/output error occurs
- * @exception ServletException if a servlet error occurs
- */
- public void service(HttpServletRequest request,
- HttpServletResponse response)
- throws ServletException, IOException
- {
-
- // Prepare our output stream
- response.setContentType("text/plain");
- PrintWriter writer = response.getWriter();
- boolean ok = true;
-
- // Construct a new instance of our parser driver
- URL url = null;
- try {
- url = getServletContext().getResource("/Xerces01.xml");
- } catch (MalformedURLException e) {
- writer.println("Xerces01 FAILED - " + e);
- e.printStackTrace(writer);
- ok = false;
- }
- Xerces01Parser parser = new Xerces01Parser();
- try {
- if (ok)
- parser.parse(url);
- } catch (Exception e) {
- writer.println("Xerces01 FAILED - " + e);
- e.printStackTrace(writer);
- ok = false;
- }
-
- // Report successful completion if OK
- if (ok)
- writer.println("Xerces01 PASSED");
- while (true) {
- String message = StaticLogger.read();
- if (message == null)
- break;
- writer.println(message);
- }
- StaticLogger.reset();
-
- }
-
-
-}
+/* ========================================================================= *
+ * *
+ * The Apache Software License, Version 1.1 *
+ * *
+ * Copyright (c) 1999, 2000, 2001 The Apache Software Foundation. *
+ * All rights reserved. *
+ * *
+ * ========================================================================= *
+ * *
+ * Redistribution and use in source and binary forms, with or without modi- *
+ * fication, are permitted provided that the following conditions are met: *
+ * *
+ * 1. Redistributions of source code must retain the above copyright notice *
+ * notice, this list of conditions and the following disclaimer. *
+ * *
+ * 2. Redistributions in binary form must reproduce the above copyright *
+ * notice, this list of conditions and the following disclaimer in the *
+ * documentation and/or other materials provided with the distribution. *
+ * *
+ * 3. The end-user documentation included with the redistribution, if any, *
+ * must include the following acknowlegement: *
+ * *
+ * "This product includes software developed by the Apache Software *
+ * Foundation <http://www.apache.org/>." *
+ * *
+ * Alternately, this acknowlegement may appear in the software itself, if *
+ * and wherever such third-party acknowlegements normally appear. *
+ * *
+ * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software *
+ * Foundation" must not be used to endorse or promote products derived *
+ * from this software without prior written permission. For written *
+ * permission, please contact <ap...@apache.org>. *
+ * *
+ * 5. Products derived from this software may not be called "Apache" nor may *
+ * "Apache" appear in their names without prior written permission of the *
+ * Apache Software Foundation. *
+ * *
+ * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES *
+ * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY *
+ * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL *
+ * THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY *
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL *
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS *
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) *
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, *
+ * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN *
+ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE *
+ * POSSIBILITY OF SUCH DAMAGE. *
+ * *
+ * ========================================================================= *
+ * *
+ * This software consists of voluntary contributions made by many indivi- *
+ * duals on behalf of the Apache Software Foundation. For more information *
+ * on the Apache Software Foundation, please see <http://www.apache.org/>. *
+ * *
+ * ========================================================================= */
+
+
+package org.apache.tester;
+
+import java.io.IOException;
+import java.io.PrintWriter;
+import java.net.MalformedURLException;
+import java.net.URL;
+import javax.servlet.*;
+import javax.servlet.http.*;
+
+
+/**
+ * Ensure that we can use the Xerces parser while included in a web application
+ * even though the servlet container might utilize its own parser for internal
+ * use.
+ *
+ * @author Amy Roh
+ * @author Craig McClanahan
+ * @version $Revision: 1.1.4.1 $ $Date: 2002/03/26 14:18:42 $
+ */
+
+public class Xerces01 extends HttpServlet {
+
+
+ // --------------------------------------------------------- Public Methods
+
+
+ /**
+ * Perform a simple SAX parse using Xerces (based on the SAXCount
+ * example application).
+ *
+ * @param request The servlet request we are processing
+ * @param response The servlet response we are creating
+ *
+ * @exception IOException if an input/output error occurs
+ * @exception ServletException if a servlet error occurs
+ */
+ public void service(HttpServletRequest request,
+ HttpServletResponse response)
+ throws ServletException, IOException
+ {
+
+ // Prepare our output stream
+ response.setContentType("text/plain");
+ PrintWriter writer = response.getWriter();
+ boolean ok = true;
+
+ // Construct a new instance of our parser driver
+ URL url = null;
+ try {
+ url = getServletContext().getResource("/Xerces01.xml");
+ } catch (MalformedURLException e) {
+ writer.println("Xerces01 FAILED - " + e);
+ e.printStackTrace(writer);
+ ok = false;
+ }
+ Xerces01Parser parser = new Xerces01Parser();
+ try {
+ if (ok)
+ parser.parse(url);
+ } catch (Exception e) {
+ writer.println("Xerces01 FAILED - " + e);
+ e.printStackTrace(writer);
+ ok = false;
+ }
+
+ // Report successful completion if OK
+ if (ok)
+ writer.println("Xerces01 PASSED");
+ while (true) {
+ String message = StaticLogger.read();
+ if (message == null)
+ break;
+ writer.println(message);
+ }
+ StaticLogger.reset();
+
+ }
+
+
+}
No revision
No revision
1.1.2.1 +40 -40 jakarta-tomcat-4.0/tester/web/Xerces01.xml
Index: Xerces01.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/Xerces01.xml,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- Xerces01.xml 13 Mar 2001 19:06:19 -0000 1.1
+++ Xerces01.xml 26 Mar 2002 14:18:42 -0000 1.1.2.1
@@ -1,40 +1,40 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<personnel>
-
- <person id="Big.Boss">
- <name><family>Boss</family> <given>Big</given></name>
- <email>chief@foo.com</email>
- <link subordinates="one.worker two.worker three.worker four.worker five.worker"/>
- </person>
-
- <person id="one.worker">
- <name><family>Worker</family> <given>One</given></name>
- <email>one@foo.com</email>
- <link manager="Big.Boss"/>
- </person>
-
- <person id="two.worker">
- <name><family>Worker</family> <given>Two</given></name>
- <email>two@foo.com</email>
- <link manager="Big.Boss"/>
- </person>
-
- <person id="three.worker">
- <name><family>Worker</family> <given>Three</given></name>
- <email>three@foo.com</email>
- <link manager="Big.Boss"/>
- </person>
-
- <person id="four.worker">
- <name><family>Worker</family> <given>Four</given></name>
- <email>four@foo.com</email>
- <link manager="Big.Boss"/>
- </person>
-
- <person id="five.worker">
- <name><family>Worker</family> <given>Five</given></name>
- <email>five@foo.com</email>
- <link manager="Big.Boss"/>
- </person>
-
-</personnel>
+<?xml version="1.0" encoding="UTF-8"?>
+<personnel>
+
+ <person id="Big.Boss">
+ <name><family>Boss</family> <given>Big</given></name>
+ <email>chief@foo.com</email>
+ <link subordinates="one.worker two.worker three.worker four.worker five.worker"/>
+ </person>
+
+ <person id="one.worker">
+ <name><family>Worker</family> <given>One</given></name>
+ <email>one@foo.com</email>
+ <link manager="Big.Boss"/>
+ </person>
+
+ <person id="two.worker">
+ <name><family>Worker</family> <given>Two</given></name>
+ <email>two@foo.com</email>
+ <link manager="Big.Boss"/>
+ </person>
+
+ <person id="three.worker">
+ <name><family>Worker</family> <given>Three</given></name>
+ <email>three@foo.com</email>
+ <link manager="Big.Boss"/>
+ </person>
+
+ <person id="four.worker">
+ <name><family>Worker</family> <given>Four</given></name>
+ <email>four@foo.com</email>
+ <link manager="Big.Boss"/>
+ </person>
+
+ <person id="five.worker">
+ <name><family>Worker</family> <given>Five</given></name>
+ <email>five@foo.com</email>
+ <link manager="Big.Boss"/>
+ </person>
+
+</personnel>
1.2.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/includeme.txt
Index: includeme.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/includeme.txt,v
retrieving revision 1.2
retrieving revision 1.2.2.1
diff -u -r1.2 -r1.2.2.1
--- includeme.txt 22 Apr 2001 21:03:47 -0000 1.2
+++ includeme.txt 26 Mar 2002 14:18:43 -0000 1.2.2.1
@@ -1 +1 @@
-This is Content of "includeme.txt"
\ No newline at end of file
+This is Content of "includeme.txt"
No revision
No revision
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/array.pl
Index: array.pl
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/array.pl,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- array.pl 1 Jun 2001 00:24:21 -0000 1.1
+++ array.pl 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -13,4 +13,4 @@
print "These are the days of the week:";
print "<p>";
-print "@days";
\ No newline at end of file
+print "@days";
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/binary.pl
Index: binary.pl
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/binary.pl,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- binary.pl 1 Jun 2001 00:24:21 -0000 1.1
+++ binary.pl 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -11,4 +11,4 @@
print "<FONT SIZE=+2>If you add one to your number, the result is <B>$counter</B>";
$counter +=5;
-print "<P>If you add 5 to that, the result is <B>$counter</B></FONT>";
\ No newline at end of file
+print "<P>If you add 5 to that, the result is <B>$counter</B></FONT>";
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/concat.pl
Index: concat.pl
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/concat.pl,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- concat.pl 1 Jun 2001 00:24:21 -0000 1.1
+++ concat.pl 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -9,4 +9,4 @@
$fullname = $first . " " . $married;
print "Content-type: text/html\n\n";
-print "Congratulations! Your married name would be $fullname.";
\ No newline at end of file
+print "Congratulations! Your married name would be $fullname.";
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/dowhile.pl
Index: dowhile.pl
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/dowhile.pl,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- dowhile.pl 1 Jun 2001 00:24:21 -0000 1.1
+++ dowhile.pl 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -13,4 +13,4 @@
--$start;
} while ($start > 0);
-print "KABOOM!";
\ No newline at end of file
+print "KABOOM!";
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/else.pl
Index: else.pl
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/else.pl,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- else.pl 1 Jun 2001 00:24:21 -0000 1.1
+++ else.pl 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -12,4 +12,4 @@
print "You ate spinach, so you get dessert!";
} else {
print "No spinach, no dessert!";
-}
\ No newline at end of file
+}
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/elsif.pl
Index: elsif.pl
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/elsif.pl,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- elsif.pl 1 Jun 2001 00:24:21 -0000 1.1
+++ elsif.pl 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -14,4 +14,4 @@
print "Broccoli's OK. Maybe you'll get dessert.";
} else {
print "No spinach, no dessert!";
-}
\ No newline at end of file
+}
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/exponents.pl
Index: exponents.pl
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/exponents.pl,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- exponents.pl 1 Jun 2001 00:24:21 -0000 1.1
+++ exponents.pl 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -10,4 +10,4 @@
print "Content-type: text/html\n\n";
print "<P>You entered $number with an exponent of $power";
-print "<P>$number raised to the $power power is $result.";
\ No newline at end of file
+print "<P>$number raised to the $power power is $result.";
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/for.pl
Index: for.pl
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/for.pl,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- for.pl 1 Jun 2001 00:24:21 -0000 1.1
+++ for.pl 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -12,4 +12,4 @@
print "$i... ";
}
-print "KABOOM!";
\ No newline at end of file
+print "KABOOM!";
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/getday.pl
Index: getday.pl
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/getday.pl,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- getday.pl 1 Jun 2001 00:24:21 -0000 1.1
+++ getday.pl 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -5,4 +5,4 @@
print "Content-type: text/html\n\n";
print "The first day of the week is $days[0]";
-print "<P>The third day of the week is $days[2]";
\ No newline at end of file
+print "<P>The third day of the week is $days[2]";
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/if.pl
Index: if.pl
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/if.pl,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- if.pl 1 Jun 2001 00:24:21 -0000 1.1
+++ if.pl 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -10,4 +10,4 @@
if ($food eq "spinach") {
print "Content-type: text/html\n\n";
print "You ate spinach, so you get dessert!\n";
-}
\ No newline at end of file
+}
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/increment.pl
Index: increment.pl
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/increment.pl,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- increment.pl 1 Jun 2001 00:24:21 -0000 1.1
+++ increment.pl 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -16,4 +16,4 @@
$counter++;
print "<BR>Again, your number incremented by 1 is $counter";
$watch = $counter++;
-print "<BR>Now we store the value of your number in a second variable, which is now equal to $watch, and then we increment your number again. It's now $counter.";
\ No newline at end of file
+print "<BR>Now we store the value of your number in a second variable, which is now equal to $watch, and then we increment your number again. It's now $counter.";
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/modifyall.pl
Index: modifyall.pl
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/modifyall.pl,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- modifyall.pl 1 Jun 2001 00:24:21 -0000 1.1
+++ modifyall.pl 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -19,4 +19,4 @@
foreach $number(@numbers) {
print "<LI>$number";
- }
\ No newline at end of file
+ }
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/preference.pl
Index: preference.pl
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/preference.pl,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- preference.pl 1 Jun 2001 00:24:21 -0000 1.1
+++ preference.pl 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -6,4 +6,4 @@
$parens_subadd = 9 - (3 + 5);
print "Content-type: text/html\n\n";
-print "div is $div, parens is $parens, subadd is $subadd and parens_subadd is $parens_subadd";
\ No newline at end of file
+print "div is $div, parens is $parens, subadd is $subadd and parens_subadd is $parens_subadd";
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/subparseform.lib
Index: subparseform.lib
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/subparseform.lib,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- subparseform.lib 1 Jun 2001 00:24:21 -0000 1.1
+++ subparseform.lib 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -40,4 +40,4 @@
}
}
}
-1;
\ No newline at end of file
+1;
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/subroutines.lib
Index: subroutines.lib
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/subroutines.lib,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- subroutines.lib 1 Jun 2001 00:24:21 -0000 1.1
+++ subroutines.lib 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -31,4 +31,4 @@
print "Content-type: text/html\n\n";
}
-1;
\ No newline at end of file
+1;
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/test-cgi.pl
Index: test-cgi.pl
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/WEB-INF/cgi/test-cgi.pl,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- test-cgi.pl 1 Jun 2001 00:24:21 -0000 1.1
+++ test-cgi.pl 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -50,4 +50,4 @@
</html>
EOM
-close OUT;
\ No newline at end of file
+close OUT;
No revision
No revision
1.1.2.1 +5 -5 jakarta-tomcat-4.0/tester/web/golden/Encoding01.txt
Index: Encoding01.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/golden/Encoding01.txt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- Encoding01.txt 23 Jul 2001 22:10:09 -0000 1.1
+++ Encoding01.txt 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -1,5 +1,5 @@
-
-
-
-<h2>Test Character</h2>
-<h2>�� Unicode = 9b5a</hr>
+
+
+
+<h2>Test Character</h2>
+<h2>�� Unicode = 9b5a</hr>
1.1.2.1 +9 -9 jakarta-tomcat-4.0/tester/web/golden/Encoding02.txt
Index: Encoding02.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/golden/Encoding02.txt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- Encoding02.txt 23 Jul 2001 23:46:02 -0000 1.1
+++ Encoding02.txt 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -1,9 +1,9 @@
-<html>
-<head>
-<title>Encoding02.jsp</title>
-</head>
-<body bgcolor="white">
-This is legal in the spec:<br>
-Joe said %> foo.
-</body>
-</html>
+<html>
+<head>
+<title>Encoding02.jsp</title>
+</head>
+<body bgcolor="white">
+This is legal in the spec:<br>
+Joe said %> foo.
+</body>
+</html>
1.1.2.1 +9 -9 jakarta-tomcat-4.0/tester/web/golden/Encoding03.txt
Index: Encoding03.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/golden/Encoding03.txt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- Encoding03.txt 23 Jul 2001 23:46:02 -0000 1.1
+++ Encoding03.txt 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -1,9 +1,9 @@
-<html>
-<head>
-<title>Encoding03.jsp</title>
-</head>
-<body bgcolor="white">
-This is not recognized as a delimiter either:<br>
-Joe said %\> bar.
-</body>
-</html>
+<html>
+<head>
+<title>Encoding03.jsp</title>
+</head>
+<body bgcolor="white">
+This is not recognized as a delimiter either:<br>
+Joe said %\> bar.
+</body>
+</html>
1.1.2.1 +4 -4 jakarta-tomcat-4.0/tester/web/golden/Include06.txt
Index: Include06.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/golden/Include06.txt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- Include06.txt 12 Jul 2001 02:41:02 -0000 1.1
+++ Include06.txt 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -1,5 +1,5 @@
-==========
+==========
Include06a output
-==========
-Include06b.jsp output
-==========
+==========
+Include06b.jsp output
+==========
1.1.2.2 +1 -1 jakarta-tomcat-4.0/tester/web/golden/JspDoc01.txt
Index: JspDoc01.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/golden/JspDoc01.txt,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- JspDoc01.txt 9 Feb 2002 16:40:27 -0000 1.1.2.1
+++ JspDoc01.txt 26 Mar 2002 14:18:43 -0000 1.1.2.2
@@ -1 +1 @@
-<a>text<b></b></a><a>text<b></b></a><c><d>text</d></c><c><d>text</d></c><e><f></f>text<f></f></e><e><f></f>text<f></f></e>
\ No newline at end of file
+<a>text<b></b></a><a>text<b></b></a><c><d>text</d></c><c><d>text</d></c><e><f></f>text<f></f></e><e><f></f>text<f></f></e>
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/golden/array.txt
Index: array.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/golden/array.txt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- array.txt 1 Jun 2001 00:23:14 -0000 1.1
+++ array.txt 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -1 +1 @@
-These are the days of the week:<p>Monday Tuesday Wednesday Thursday Friday Saturday Sunday
\ No newline at end of file
+These are the days of the week:<p>Monday Tuesday Wednesday Thursday Friday Saturday Sunday
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/golden/binary.txt
Index: binary.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/golden/binary.txt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- binary.txt 1 Jun 2001 00:23:14 -0000 1.1
+++ binary.txt 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -1 +1 @@
-<FONT SIZE=+2>If you add one to your number, the result is <B>103</B><P>If you add 5 to that, the result is <B>108</B></FONT>
\ No newline at end of file
+<FONT SIZE=+2>If you add one to your number, the result is <B>103</B><P>If you add 5 to that, the result is <B>108</B></FONT>
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/golden/days.txt
Index: days.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/golden/days.txt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- days.txt 1 Jun 2001 00:23:14 -0000 1.1
+++ days.txt 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -1 +1 @@
-These are the days of the week:<P>Monday Tuesday Wednesday Thursday Friday Saturday Sunday
\ No newline at end of file
+These are the days of the week:<P>Monday Tuesday Wednesday Thursday Friday Saturday Sunday
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/golden/dowhile.txt
Index: dowhile.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/golden/dowhile.txt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- dowhile.txt 1 Jun 2001 00:23:14 -0000 1.1
+++ dowhile.txt 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -1 +1 @@
-<P>Starting countdown...10... 9... 8... 7... 6... 5... 4... 3... 2... 1... KABOOM!
\ No newline at end of file
+<P>Starting countdown...10... 9... 8... 7... 6... 5... 4... 3... 2... 1... KABOOM!
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/golden/exponents.txt
Index: exponents.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/golden/exponents.txt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- exponents.txt 1 Jun 2001 00:23:14 -0000 1.1
+++ exponents.txt 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -1 +1 @@
-<P>You entered 2 with an exponent of 4<P>2 raised to the 4 power is 16.
\ No newline at end of file
+<P>You entered 2 with an exponent of 4<P>2 raised to the 4 power is 16.
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/golden/getday.txt
Index: getday.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/golden/getday.txt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- getday.txt 1 Jun 2001 00:23:14 -0000 1.1
+++ getday.txt 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -1 +1 @@
-The first day of the week is Sunday<P>The third day of the week is Tuesday
\ No newline at end of file
+The first day of the week is Sunday<P>The third day of the week is Tuesday
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/golden/increment.txt
Index: increment.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/golden/increment.txt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- increment.txt 1 Jun 2001 00:23:14 -0000 1.1
+++ increment.txt 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -1 +1 @@
-Your number incremented by 1 is 8<BR>Your number, incremented again by 1, is now 9. If we store that operation, its value is also 9.<HR>Let's start over, with your original number 7<BR>Again, your number incremented by 1 is 8<BR>Now we store the value of your number in a second variable, which is now equal to 8, and then we increment your number again. It's now 9.
\ No newline at end of file
+Your number incremented by 1 is 8<BR>Your number, incremented again by 1, is now 9. If we store that operation, its value is also 9.<HR>Let's start over, with your original number 7<BR>Again, your number incremented by 1 is 8<BR>Now we store the value of your number in a second variable, which is now equal to 8, and then we increment your number again. It's now 9.
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/golden/modifyall.txt
Index: modifyall.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/golden/modifyall.txt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- modifyall.txt 1 Jun 2001 00:23:14 -0000 1.1
+++ modifyall.txt 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -1 +1 @@
-The numbers you entered were:<LI>289<P>The square roots of those numbers are: <LI>17
\ No newline at end of file
+The numbers you entered were:<LI>289<P>The square roots of those numbers are: <LI>17
1.1.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/golden/preference.txt
Index: preference.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/golden/preference.txt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- preference.txt 1 Jun 2001 00:23:14 -0000 1.1
+++ preference.txt 26 Mar 2002 14:18:43 -0000 1.1.2.1
@@ -1 +1 @@
-div is 11, parens is 5, subadd is 11 and parens_subadd is 1
\ No newline at end of file
+div is 11, parens is 5, subadd is 11 and parens_subadd is 1
No revision
No revision
1.2.2.1 +1 -1 jakarta-tomcat-4.0/tester/web/ssidir/includeme.txt
Index: includeme.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/tester/web/ssidir/includeme.txt,v
retrieving revision 1.2
retrieving revision 1.2.2.1
diff -u -r1.2 -r1.2.2.1
--- includeme.txt 22 Apr 2001 21:03:47 -0000 1.2
+++ includeme.txt 26 Mar 2002 14:18:44 -0000 1.2.2.1
@@ -1 +1 @@
-This is Content of "includeme.txt"
\ No newline at end of file
+This is Content of "includeme.txt"
No revision
No revision
1.5.2.1 +7 -6 jakarta-tomcat-4.0/webapps/examples/WEB-INF/classes/compressionFilters/CompressionFilter.java
Index: CompressionFilter.java
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/examples/WEB-INF/classes/compressionFilters/CompressionFilter.java,v
retrieving revision 1.5
retrieving revision 1.5.2.1
diff -u -r1.5 -r1.5.2.1
--- CompressionFilter.java 6 Sep 2001 23:05:08 -0000 1.5
+++ CompressionFilter.java 26 Mar 2002 14:18:44 -0000 1.5.2.1
@@ -1,8 +1,8 @@
/*
* CompressionFilter.java
- * $Header: /home/cvs/jakarta-tomcat-4.0/webapps/examples/WEB-INF/classes/compressionFilters/CompressionFilter.java,v 1.5 2001/09/06 23:05:08 remm Exp $
- * $Revision: 1.5 $
- * $Date: 2001/09/06 23:05:08 $
+ * $Header: /home/cvs/jakarta-tomcat-4.0/webapps/examples/WEB-INF/classes/compressionFilters/CompressionFilter.java,v 1.5.2.1 2002/03/26 14:18:44 jfclere Exp $
+ * $Revision: 1.5.2.1 $
+ * $Date: 2002/03/26 14:18:44 $
*
* ====================================================================
*
@@ -74,13 +74,13 @@
import javax.servlet.ServletResponse;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
-
+
/**
* Implementation of <code>javax.servlet.Filter</code> used to compress
* the ServletResponse if it is bigger than a threshold.
*
* @author Amy Roh
- * @version $Revision: 1.5 $, $Date: 2001/09/06 23:05:08 $
+ * @version $Revision: 1.5.2.1 $, $Date: 2002/03/26 14:18:44 $
*/
public class CompressionFilter implements Filter{
@@ -167,7 +167,8 @@
Enumeration e =
((HttpServletRequest)request).getHeaders("Accept-Encoding");
while (e.hasMoreElements()) {
- String name = (String)e.nextElement();
if (name.indexOf("gzip") != -1) {
+ String name = (String)e.nextElement();
+ if (name.indexOf("gzip") != -1) {
if (debug > 0) {
System.out.println("supports compression");
}
1.3.2.1 +6 -5 jakarta-tomcat-4.0/webapps/examples/WEB-INF/classes/compressionFilters/CompressionFilterTestServlet.java
Index: CompressionFilterTestServlet.java
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/examples/WEB-INF/classes/compressionFilters/CompressionFilterTestServlet.java,v
retrieving revision 1.3
retrieving revision 1.3.2.1
diff -u -r1.3 -r1.3.2.1
--- CompressionFilterTestServlet.java 6 Sep 2001 04:18:54 -0000 1.3
+++ CompressionFilterTestServlet.java 26 Mar 2002 14:18:44 -0000 1.3.2.1
@@ -1,8 +1,8 @@
/*
* CompressionFilterTestServlet.java
- * $Header: /home/cvs/jakarta-tomcat-4.0/webapps/examples/WEB-INF/classes/compressionFilters/CompressionFilterTestServlet.java,v 1.3 2001/09/06 04:18:54 amyroh Exp $
- * $Revision: 1.3 $
- * $Date: 2001/09/06 04:18:54 $
+ * $Header: /home/cvs/jakarta-tomcat-4.0/webapps/examples/WEB-INF/classes/compressionFilters/CompressionFilterTestServlet.java,v 1.3.2.1 2002/03/26 14:18:44 jfclere Exp $
+ * $Revision: 1.3.2.1 $
+ * $Date: 2002/03/26 14:18:44 $
*
* ====================================================================
*
@@ -73,7 +73,7 @@
/**
* Very Simple test servlet to test compression filter
* @author Amy Roh
- * @version $Revision: 1.3 $, $Date: 2001/09/06 04:18:54 $
+ * @version $Revision: 1.3.2.1 $, $Date: 2002/03/26 14:18:44 $
*/
public class CompressionFilterTestServlet extends HttpServlet {
@@ -86,7 +86,8 @@
Enumeration e = ((HttpServletRequest)request).getHeaders("Accept-Encoding");
while (e.hasMoreElements()) {
- String name = (String)e.nextElement();
out.println(name);
+ String name = (String)e.nextElement();
+ out.println(name);
if (name.indexOf("gzip") != -1) {
out.println("gzip supported -- able to compress");
}
No revision
No revision
1.1.4.1 +1 -1 jakarta-tomcat-4.0/webapps/examples/jsp/forward/one.jsp
Index: one.jsp
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/examples/jsp/forward/one.jsp,v
retrieving revision 1.1
retrieving revision 1.1.4.1
diff -u -r1.1 -r1.1.4.1
--- one.jsp 16 Oct 2000 21:33:11 -0000 1.1
+++ one.jsp 26 Mar 2002 14:18:44 -0000 1.1.4.1
@@ -8,4 +8,4 @@
<font color="red">
VM Memory usage < 50%.
-</html>
\ No newline at end of file
+</html>
1.1.4.1 +1 -1 jakarta-tomcat-4.0/webapps/examples/jsp/forward/two.html
Index: two.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/examples/jsp/forward/two.html,v
retrieving revision 1.1
retrieving revision 1.1.4.1
diff -u -r1.1 -r1.1.4.1
--- two.html 16 Oct 2000 21:33:11 -0000 1.1
+++ two.html 26 Mar 2002 14:18:44 -0000 1.1.4.1
@@ -8,4 +8,4 @@
<font color="red">
VM Memory usage > 50%.
-</html>
\ No newline at end of file
+</html>
No revision
No revision
1.1.4.1 +1 -1 jakarta-tomcat-4.0/webapps/examples/jsp/jsptoserv/hello.jsp
Index: hello.jsp
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/examples/jsp/jsptoserv/hello.jsp,v
retrieving revision 1.1
retrieving revision 1.1.4.1
diff -u -r1.1 -r1.1.4.1
--- hello.jsp 17 Aug 2000 00:58:14 -0000 1.1
+++ hello.jsp 26 Mar 2002 14:18:44 -0000 1.1.4.1
@@ -11,4 +11,4 @@
Servlet.
</h1>
-</html>
\ No newline at end of file
+</html>
1.1.4.1 +1 -1 jakarta-tomcat-4.0/webapps/examples/jsp/jsptoserv/jsptoservlet.jsp
Index: jsptoservlet.jsp
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/examples/jsp/jsptoserv/jsptoservlet.jsp,v
retrieving revision 1.1
retrieving revision 1.1.4.1
diff -u -r1.1 -r1.1.4.1
--- jsptoservlet.jsp 17 Aug 2000 00:58:14 -0000 1.1
+++ jsptoservlet.jsp 26 Mar 2002 14:18:44 -0000 1.1.4.1
@@ -8,4 +8,4 @@
<!-- Forward to a servlet -->
<jsp:forward page="/servlet/servletToJsp" />
-</html>
\ No newline at end of file
+</html>
1.1.4.1 +1 -1 jakarta-tomcat-4.0/webapps/examples/jsp/jsptoserv/jts.txt
Index: jts.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/examples/jsp/jsptoserv/jts.txt,v
retrieving revision 1.1
retrieving revision 1.1.4.1
diff -u -r1.1 -r1.1.4.1
--- jts.txt 17 Aug 2000 00:58:14 -0000 1.1
+++ jts.txt 26 Mar 2002 14:18:44 -0000 1.1.4.1
@@ -8,4 +8,4 @@
<!-- Forward to a servlet -->
<jsp:forward page="/servlet/servletToJsp" />
-</html>
\ No newline at end of file
+</html>
No revision
No revision
1.1.2.1 +132 -132 jakarta-tomcat-4.0/webapps/tomcat-docs/introduction.xml
Index: introduction.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/introduction.xml,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- introduction.xml 6 Aug 2001 20:24:07 -0000 1.1
+++ introduction.xml 26 Mar 2002 14:18:44 -0000 1.1.2.1
@@ -1,132 +1,132 @@
-<?xml version="1.0"?>
-<!DOCTYPE document [
- <!ENTITY project SYSTEM "project.xml">
-]>
-<document>
-
- &project;
-
- <properties>
- <author email="rslifka@sfu.ca">Robert Slifka</author>
- <title>Introduction</title>
- </properties>
-
-<body>
-
-
-<section name="Introduction">
-
-<p>For administrators and web developers alike, there are some important bits
-of information you should familiarize yourself with before starting out. This
-document serves as a brief introduction to some of the concepts and
-terminology behind the Tomcat container. As well, where to go when you need
-help.</p>
-
-</section>
-
-
-<section name="Terminology">
-
-<p>In the course of reading these documents, you'll run across a number of
-terms; some specific to Tomcat, and others defined by the
-<a href="http://java.sun.com/products/servlet/">Servlet</a> or
-<a href="http://java.sun.com/products/jsp/">JSP</a> specifications.</p>
-
-<ul>
-<li><strong>Context</strong> - In a nutshell, a Context is a
- web application.</li>
-<li><strong>Term2</strong> - This is it.</li>
-<li><strong>Term3</strong> - This is it!</li>
-</ul>
-
-</section>
-
-
-<section name="Directories and Files">
-
-<p>Throughout the docs, you'll notice there are numerous references to
-<strong>$CATALINA_HOME</strong>. This represents the root of your Tomcat
-installation. When we say, "This information can be found in your
-$CATALINA_HOME/README.txt file" we mean to look at the README.txt file at the
-root of your Tomcat install.</p>
-
-<p>For the complete description of the Tomcat distribution, each folder can be
-found in the <a href="README.txt">README.txt</a> file, residing in the root
-directory of your Tomcat installation. Here, we will cover the ones where
-you'll be spending the majority of your time.</p>
-
-<ul>
-<li><strong>/bin</strong> - Startup, shutdown, and other scripts. The
- <code>*.sh</code> files (for Unix systems) are functional duplicates of
- the <code>*.bat</code> files (for Windows systems). Since the Win32
- command-line lacks certain functionality, there are some additional
- files in here.</li>
-<li><strong>/conf</strong> - Configuration files and related DTDs. The most
- important file in here is server.xml. It is the main configuration file
- for the container.</li>
-<li><strong>/logs</strong> - Log files are here by default.</li>
-<li><strong>/webapps</strong> - This is where your webapps go.</li>
-</ul>
-
-</section>
-
-
-<section name="Configuring Tomcat">
-
-<p>This section will acquaint you with the basic information used during
-the configuration of the container.</p>
-
-<p>All of the information in the configuration files is read at startup,
-meaning that any change to the files necessitates a restart of the container.
-</p>
-
-</section>
-
-
-<section name="Where to Go for Help">
-
-<p>While we've done our best to ensure that these documents are clearly
-written and easy to understand, we may have missed something. Provided
-below are various web sites and mailing lists in case you get stuck.</p>
-
-<p>As Tomcat 4 is a new release of Tomcat, keep in mind that some of the
-issues and solutions vary between the major versions of Tomcat (3.x versus
-4.x). As you search around the web, there will be some documentation that
-is not relevant to Tomcat 4, but 3.x. Doing 3.x things to 4.0 will probably
-not work in most cases as the server.xml files are very different.</p>
-
-<ul>
-<li>Current document - most documents will list potential hangups. Be sure
- to fully read the relevant documentation as it will save you much time
- and effort. There's nothing like scouring the web only to find out that
- the answer was right in front of you all along!</li>
-<li>Jakarta <a href="http://jakarta.apache.org:8080/jyve-faq/Turbine/screen/MainMenu/action/SetAll/screen/DisplayTopics/faq_id/12/project_id/2;jsessionid=36lqy9k9x1">FAQ-o-matic</a>
- - a repository of FAQs for the various Jakarta subprojects, including
- Tomcat of course.</li>
-<li>Tomcat FAQ at <a href="http://www.jguru.com/faq/home.jsp?topic=Tomcat">jGuru</a></li>
-<li>Tomcat mailing list archives - numerous sites archive the Tomcat mailing
- lists. Since the links change over time, clicking here will search
- <a href="http://www.google.com/search?q=tomcat+mailing+list+archives">Google</a>.
- </li>
-<li>The TOMCAT-USER mailing list, which you can subscribe to
- <a href="http://jakarta.apache.org/site/mail.html">here</a>. If you don't
- get a reply, then there's a good chance that your question was probably
- answered in the list archives or one of the FAQs. Although questions
- about web application development in general are sometimes asked and
- answered, please focus your questions on Tomcat-specific issues.</li>
-<li>The TOMCAT-DEV mailing list, which you can subscribe to
- <a href="http://jakarta.apache.org/site/mail.html">here</a>. This list is
- <strong>reserved</strong> for discussions about the development of Tomcat
- itself. Questions about Tomcat configuration, and the problems you run
- into while developing and running applications, will normally be more
- appropriate on the TOMCAT-USER list instead.</li>
-</ul>
-
-<p>And, if you think something should be in the docs, by all means let us know
-on the TOMCAT-DEV list, or send one of the doc authors email.</p>
-
-</section>
-
-</body>
-
-</document>
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document>
+
+ &project;
+
+ <properties>
+ <author email="rslifka@sfu.ca">Robert Slifka</author>
+ <title>Introduction</title>
+ </properties>
+
+<body>
+
+
+<section name="Introduction">
+
+<p>For administrators and web developers alike, there are some important bits
+of information you should familiarize yourself with before starting out. This
+document serves as a brief introduction to some of the concepts and
+terminology behind the Tomcat container. As well, where to go when you need
+help.</p>
+
+</section>
+
+
+<section name="Terminology">
+
+<p>In the course of reading these documents, you'll run across a number of
+terms; some specific to Tomcat, and others defined by the
+<a href="http://java.sun.com/products/servlet/">Servlet</a> or
+<a href="http://java.sun.com/products/jsp/">JSP</a> specifications.</p>
+
+<ul>
+<li><strong>Context</strong> - In a nutshell, a Context is a
+ web application.</li>
+<li><strong>Term2</strong> - This is it.</li>
+<li><strong>Term3</strong> - This is it!</li>
+</ul>
+
+</section>
+
+
+<section name="Directories and Files">
+
+<p>Throughout the docs, you'll notice there are numerous references to
+<strong>$CATALINA_HOME</strong>. This represents the root of your Tomcat
+installation. When we say, "This information can be found in your
+$CATALINA_HOME/README.txt file" we mean to look at the README.txt file at the
+root of your Tomcat install.</p>
+
+<p>For the complete description of the Tomcat distribution, each folder can be
+found in the <a href="README.txt">README.txt</a> file, residing in the root
+directory of your Tomcat installation. Here, we will cover the ones where
+you'll be spending the majority of your time.</p>
+
+<ul>
+<li><strong>/bin</strong> - Startup, shutdown, and other scripts. The
+ <code>*.sh</code> files (for Unix systems) are functional duplicates of
+ the <code>*.bat</code> files (for Windows systems). Since the Win32
+ command-line lacks certain functionality, there are some additional
+ files in here.</li>
+<li><strong>/conf</strong> - Configuration files and related DTDs. The most
+ important file in here is server.xml. It is the main configuration file
+ for the container.</li>
+<li><strong>/logs</strong> - Log files are here by default.</li>
+<li><strong>/webapps</strong> - This is where your webapps go.</li>
+</ul>
+
+</section>
+
+
+<section name="Configuring Tomcat">
+
+<p>This section will acquaint you with the basic information used during
+the configuration of the container.</p>
+
+<p>All of the information in the configuration files is read at startup,
+meaning that any change to the files necessitates a restart of the container.
+</p>
+
+</section>
+
+
+<section name="Where to Go for Help">
+
+<p>While we've done our best to ensure that these documents are clearly
+written and easy to understand, we may have missed something. Provided
+below are various web sites and mailing lists in case you get stuck.</p>
+
+<p>As Tomcat 4 is a new release of Tomcat, keep in mind that some of the
+issues and solutions vary between the major versions of Tomcat (3.x versus
+4.x). As you search around the web, there will be some documentation that
+is not relevant to Tomcat 4, but 3.x. Doing 3.x things to 4.0 will probably
+not work in most cases as the server.xml files are very different.</p>
+
+<ul>
+<li>Current document - most documents will list potential hangups. Be sure
+ to fully read the relevant documentation as it will save you much time
+ and effort. There's nothing like scouring the web only to find out that
+ the answer was right in front of you all along!</li>
+<li>Jakarta <a href="http://jakarta.apache.org:8080/jyve-faq/Turbine/screen/MainMenu/action/SetAll/screen/DisplayTopics/faq_id/12/project_id/2;jsessionid=36lqy9k9x1">FAQ-o-matic</a>
+ - a repository of FAQs for the various Jakarta subprojects, including
+ Tomcat of course.</li>
+<li>Tomcat FAQ at <a href="http://www.jguru.com/faq/home.jsp?topic=Tomcat">jGuru</a></li>
+<li>Tomcat mailing list archives - numerous sites archive the Tomcat mailing
+ lists. Since the links change over time, clicking here will search
+ <a href="http://www.google.com/search?q=tomcat+mailing+list+archives">Google</a>.
+ </li>
+<li>The TOMCAT-USER mailing list, which you can subscribe to
+ <a href="http://jakarta.apache.org/site/mail.html">here</a>. If you don't
+ get a reply, then there's a good chance that your question was probably
+ answered in the list archives or one of the FAQs. Although questions
+ about web application development in general are sometimes asked and
+ answered, please focus your questions on Tomcat-specific issues.</li>
+<li>The TOMCAT-DEV mailing list, which you can subscribe to
+ <a href="http://jakarta.apache.org/site/mail.html">here</a>. This list is
+ <strong>reserved</strong> for discussions about the development of Tomcat
+ itself. Questions about Tomcat configuration, and the problems you run
+ into while developing and running applications, will normally be more
+ appropriate on the TOMCAT-USER list instead.</li>
+</ul>
+
+<p>And, if you think something should be in the docs, by all means let us know
+on the TOMCAT-DEV list, or send one of the doc authors email.</p>
+
+</section>
+
+</body>
+
+</document>
1.6.2.2 +754 -754 jakarta-tomcat-4.0/webapps/tomcat-docs/jndi-resources-howto.xml
Index: jndi-resources-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/jndi-resources-howto.xml,v
retrieving revision 1.6.2.1
retrieving revision 1.6.2.2
diff -u -r1.6.2.1 -r1.6.2.2
--- jndi-resources-howto.xml 10 Oct 2001 18:11:26 -0000 1.6.2.1
+++ jndi-resources-howto.xml 26 Mar 2002 14:18:44 -0000 1.6.2.2
@@ -1,754 +1,754 @@
-<?xml version="1.0"?>
-<!DOCTYPE document [
- <!ENTITY project SYSTEM "project.xml">
-]>
-<document>
-
- &project;
-
- <properties>
- <author email="craigmcc@apache.org">Craig R. McClanahan</author>
- <title>JNDI Resources HOW-TO</title>
- </properties>
-
-<body>
-
-
-<section name="Introduction">
-
-<p>Tomcat 4 provides a JNDI <strong>InitialContext</strong> implementation
-instance to web applications running under it, in a manner that is compatible
-with those provided by a <a href="http://java.sun.com/j2ee">Java2 Enterprise
-Edition</a> application server. Entries in this <code>InitialContext</code>
-are configured in the <code>$CATALINA_HOME/conf/server.xml</code> file, and
-may be referenced by the following elements in the web application deployment
-descriptor (<code>/WEB-INF/web.xml</code>) of your web application:</p>
-<ul>
-<li><code><strong><env-entry></strong></code> - Environment entry, a
- single-value parameter that can be used to configure how the application
- will operate.</li>
-<li><code><strong><resource-ref></strong></code> - Resource reference,
- which is typically to an object factory for resources such as a JDBC
- <code>DataSource</code>, a JavaMail <code>Session</code>, or custom
- object factories configured into Tomcat 4.</li>
-<li><code><strong><resource-env-ref></strong></code> - Resource
- environment reference, a new variation of <code>resource-ref</code>
- added in Servlet 2.3 that is simpler to configure for resources
- that do not require authentication information.</li>
-</ul>
-
-<p>The <code>InitialContext</code> is configured as a web application is
-initially deployed, and is made available to web application components (for
-read-only access). All configured entries and resources will be placed in
-the <code>java:comp/env</code> portion of the JNDI namespace, so a typical
-access to a resource - in this case, to a JDBC <code>DataSource</code> -
-would look something like this:</p>
-<source>
-// Obtain our environment naming context
-Context initCtx = new InitialContext();
-Context envCtx = (Context) initCtx.lookup("java:comp/env");
-
-// Look up our data source
-DataSource ds = (DataSource)
- envCtx.lookup("jdbc/EmployeeDB");
-
-// Allocate and use a connection from the pool
-Connection conn = ds.getConnection();
-... use this connection to access the database ...
-conn.close();
-</source>
-
-<p>See the following Specifications for more information about programming APIs
-for JNDI, and for the features supported by Java2 Enterprise Edition (J2EE)
-servers, which Tomcat emulates for the services that it provides:</p>
-<ul>
-<li><a href="http://java.sun.com/products/jndi/#download">Java Naming and
- Directory Interface</a> (included in JDK 1.4, available separately for
- prior JDK versions)</li>
-<li><a href="http://java.sun.com/j2ee/download.html">J2EE Platform
- Specification</a> (in particular, see Chapter 5 on <em>Naming</em>)</li>
-</ul>
-
-</section>
-
-
-<section name="Configuring JNDI Resources">
-
-<p>Each available JNDI Resource is configured based on inclusion of the
-following elements in the <code>$CATALINA_HOME/conf/server.xml</code>
-file:</p>
-<ul>
-<li><a href="config/context.html#Environment Entries"><Environment></a> -
- Configure names and values for scalar environment entries that will be
- exposed to the web application through the JNDI
- <code>InitialContext</code> (equivalent to the inclusion of an
- <code><env-entry></code> element in the web application
- deployment descriptor).</li>
-<li><a href="config/context.html#Resource Definitions"><Resource></a> -
- Configure the name and data type of a resource made available to the
- application (equivalent to the inclusion of a
- <code><resource-ref></code> element in the web application
- deployment descriptor).</li>
-<li><a href="config/context.html#Resource Parameters"><ResourceParams></a> -
- Configure the Java class name of the resource factory implementation to be
- used, as well as JavaBeans properties used to configure that resource
- factory.</li>
-</ul>
-
-<p>Any number of these elements may be nested inside a
-<a href="config/context.html"><Context></a> element (to be associated
-only with that particular web application) or inside a
-<a href="config/defaultcontext.html"><DefaultContext></a> element
-(used to set the default configuration characteristics for automatically
-deloyed applications).</p>
-
-<p>In addition, the names and values of all <code><env-entry></code>
-elements included in the web application deployment descriptor
-(<code>/WEB-INF/web.xml</code>) are configured into the initial context as
-well, overriding corresponding values from <code>conf/server.xml</code>
-<strong>only</strong> if allowed by the corresponding
-<code><Environment></code> element (by setting the
-<code>override</code> attribute to "true").</p>
-
-</section>
-
-
-<section name="Tomcat Standard Resource Factories">
-
- <p>Tomcat 4 includes a series of standard resource factories that can
- provide services to your web applications, but give you configuration
- flexibility (in <code>$CATALINA_HOME/conf/server.xml</code>) without
- modifying the web application or the deployment descriptor. Each
- subsection below details the configuration and usage of the standard
- resource factories.</p>
-
- <p>See <a href="#Adding Custom Resource Factories">Adding Custom
- Resource Factories</a> for information about how to create, install,
- configure, and use your own custom resource factory classes with
- Tomcat 4.</p>
-
- <p><em>NOTE</em> - Of the standard resource factories, only the
- "JDBC Data Source" and "User Transaction" factories are mandated to
- be available on other platforms, and then they are required only if
- the platform implements the Java2 Enterprise Edition (J2EE) specs.
- All other standard resource factories, plus custom resource factories
- that you write yourself, are specific to Tomcat and cannot be assumed
- to be available on other containers.</p>
-
- <subsection name="Generic JavaBean Resources">
-
- <h3>0. Introduction</h3>
-
- <p>This resource factory can be used to create objects of <em>any</em>
- Java class that conforms to standard JavaBeans naming conventions (i.e.
- it has a zero-arguments constructor, and has property setters that
- conform to the setFoo() naming pattern. The resource factory will
- create a new instance of the appropriate bean class every time a
- <code>lookup()</code> for this entry is made.</p>
-
- <p>The steps required to use this facility are described below.</p>
-
- <h3>1. Create Your JavaBean Class</h3>
-
- <p>Create the JavaBean class which will be instantiated each time
- that the resource factory is looked up. For this example, assume
- you create a class <code>com.mycompany.MyBean</code>, which looks
- like this:</p>
-
-<source>
-package com.mycompany;
-
-public class MyBean {
-
- private String foo = "Default Foo";
-
- public String getFoo() {
- return (this.foo);
- }
-
- public void setFoo(String foo) {
- this.foo = foo;
- }
-
- private int bar = 0;
-
- public int getBar() {
- return (this.bar);
- }
-
- public void setBar(int bar) {
- this.bar = bar;
- }
-
-
-}
-</source>
-
- <h3>2. Declare Your Resource Requirements</h3>
-
- <p>Next, modify your web application deployment descriptor
- (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which
- you will request new instances of this bean. The simplest approach is
- to use a <code><resource-env-ref></code> element, like this:</p>
-
-<source>
-<resource-env-ref>
- <Description>
- Object factory for MyBean instances.
- </Description>
- <resource-env-ref-name>
- bean/MyBeanFactory
- </resource-env-ref-name>
- <resource-env-ref-type>
- com.mycompany.MyBean
- </resource-env-ref-type>
-<resource-env-ref>
-</source>
-
- <p><strong>WARNING</strong> - Be sure you respect the element ordering
- that is required by the DTD for web application deployment descriptors!
- See the
- <a href="http://java.sun.com/products/servlet/download.html">Servlet
- Specification</a> for details.</p>
-
- <h3>3. Code Your Application's Use Of This Resource</h3>
-
- <p>A typical use of this resource environment reference might look
- like this:</p>
-
-<source>
-Context initCtx = new InitialContext();
-Context envCtx = (Context) initCtx.lookup("java:comp/env");
-MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");
-
-writer.println("foo = " + bean.getFoo() + ", bar = " +
- bean.getBar());
-</source>
-
- <h3>4. Configure Tomcat's Resource Factory</h3>
-
- <p>To configure Tomcat's resource factory, add an elements like this to the
- <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
- <code>Context</code> element for this web application (or nested inside
- a <code>DefaultContext</code> element for the surrounding
- <code><Host></code> or <code><Engine></code> element.</p>
-<source>
-<Context ...>
- ...
- <Resource name="bean/MyBeanFactory" auth="Container"
- type="com.mycompany.MyBean"/>
- <ResourceParams name="bean/MyBeanFactory">
- <parameter>
- <name>factory</name>
- <value>org.apache.naming.factory.BeanFactory</value>
- </parameter>
- <parameter>
- <name>bar</name>
- <value>23</value>
- </parameter>
- </ResourceParams>
- ...
-</Context>
-</source>
-
- <p>Note that the resource name (here, <code>bean/MyBeanFactory</code>
- must match the value specified in the web application deployment
- descriptor. We are also initializing the value of the <code>bar</code>
- property, which will cause <code>setBar(23)</code> to be called before
- the new bean is returned. Because we are not initializing the
- <code>foo</code> property (although we could have), the bean will
- contain whatever default value is set up by its constructor.</p>
-
- </subsection>
-
-
- <subsection name="JavaMail Sessions">
-
- <h3>0. Introduction</h3>
-
- <p>In many web applications, sending electronic mail messages is a
- required part of the system's functionality. The
- <a href="http://java.sun.com/products/javamail">Java Mail</a> API
- makes this process relatively straightforward, but requires many
- configuration details that the client application must be aware of
- (including the name of the SMTP host to be used for message sending).</p>
-
- <p>Tomcat 4 includes a standard resource factory that will create
- <code>javax.mail.Session</code> session instances for you, already
- connected to the SMTP server that is configured in <code>server.xml</code>.
- In this way, the application is totally insulated from changes in the
- email server configuration environment - it simply asks for, and receives,
- a preconfigured session whenever needed.</p>
-
- <p>The steps required for this are outlined below.</p>
-
- <h3>1. Declare Your Resource Requirements</h3>
-
- <p>The first thing you should do is modify the web application deployment
- descriptor (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under
- which you will look up preconfigured sessions. By convention, all such
- names should resolve to the <code>mail</code> subcontext (relative to the
- standard <code>java:comp/env</code> naming context that is the root of
- all provided resource factories. A typical <code>web.xml</code> entry
- might look like this:</p>
-<source>
-<resource-ref>
- <description>
- Resource reference to a factory for javax.mail.Session
- instances that may be used for sending electronic mail
- messages, preconfigured to connect to the appropriate
- SMTP server.
- </description>
- <res-ref-name>
- mail/Session
- </res-ref-name>
- <res-type>
- javax.mail.Session
- </res-type>
- <res-auth>
- Container
- </res-auth>
-</resource-ref>
-</source>
-
- <p><strong>WARNING</strong> - Be sure you respect the element ordering
- that is required by the DTD for web application deployment descriptors!
- See the
- <a href="http://java.sun.com/products/servlet/download.html">Servlet
- Specification</a> for details.</p>
-
- <h3>2. Code Your Application's Use Of This Resource</h3>
-
- <p>A typical use of this resource reference might look like this:</p>
-<source>
-Context initCtx = new InitialContext();
-Context envCtx = (Context) initCtx.lookup("java:comp/env");
-Session session = (Session) envCtx.lookup("mail/Session");
-
-Message message = new MimeMessage(session);
-message.setFrom(new InternetAddress(request.getParameter("from"));
-InternetAddress to[] = new InternetAddress[1];
-to[0] = new InternetAddress(request.getParameter("to"));
-message.setRecipients(Message.RecipientType.TO, to);
-message.setSubject(request.getParameter("subject"));
-message.setContent(request.getParameter("content"), "text/plain");
-Transport.send(message);
-</source>
-
- <p>Note that the application uses the same resource reference name
- that was declared in the web application deployment descriptor. This
- is matched up against the resource factory that is configured in
- <code>$CATALINA_HOME/conf/server.xml</code>, as described below.</p>
-
- <h3>3. Configure Tomcat's Resource Factory</h3>
-
- <p>To configure Tomcat's resource factory, add an elements like this to the
- <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
- <code>Context</code> element for this web application (or nested inside
- a <code>DefaultContext</code> element for the surrounding
- <code><Host></code> or <code><Engine></code> element.</p>
-<source>
-<Context ...>
- ...
- <Resource name="mail/Session" auth="Container"
- type="javax.mail.Session"/>
- <ResourceParams name="mail/Session">
- <parameter>
- <name>mail.smtp.host</name>
- <value>localhost</value>
- </parameter>
- </ResourceParams>
- ...
-</Context>
-</source>
-
- <p>Note that the resource name (here, <code>mail/Session</code>) must
- match the value specified in the web application deployment descriptor.
- Customize the value of the <code>mail.smtp.host</code> parameter to
- point at the server that provides SMTP service for your network.</p>
-
- <h3>Example Application</h3>
-
- <p>The <code>/examples</code> application included with Tomcat contains
- an example of utilizing this resource factory. It is accessed via the
- "JSP Examples" link. The source code for the servlet that actually
- sends the mail message is in
- <code>/WEB-INF/classes/SendMailServlet.java</code>.</p>
-
- <p><strong>WARNING</strong> - The default configuration assumes that
- there is an SMTP server listing on port 25 on <code>localhost</code>.
- If this is not the case, edit the
- <code>$CATALINA_HOME/conf/server.xml</code> file, and modify the
- parameter value for the <code>mail.smtp.host</code> parameter to be
- the host name of an SMTP server on your network.</p>
-
- </subsection>
-
- <subsection name="JDBC Data Sources">
-
- <h3>0. Introduction</h3>
-
- <p>Many web applications need to access a database via a JDBC driver,
- to support the functionality required by that application. The J2EE
- Platform Specification requires J2EE Application Servers to make
- available a <em>DataSource</em> implementation (that is, a connection
- pool for JDBC connections) for this purpose. Tomcat 4 offers exactly
- the same support, so that database-based applications you develop on
- Tomcat using this service will run unchanged on any J2EE server.</p>
-
- <p>For information about JDBC, you should consult the following:</p>
- <ul>
- <li><a href="http://java.sun.com/products/jdbc/">http://java.sun.com/products/jdbc/</a> -
- Home page for information about Java Database Connectivity.</li>
- <li><a href="http://java.sun.com/j2se/1.3/docs/guide/jdbc/spec2/jdbc2.1.frame.html">http://java.sun.com/j2se/1.3/docs/guide/jdbc/spec2/jdbc2.1.frame.html</a> -
- The JDBC 2.1 API Specification.</li>
- <li><a href="http://java.sun.com/products/jdbc/jdbc20.stdext.pdf">http://java.sun.com/products/jdbc/jdbc20.stdext.pdf</a> -
- The JDBC 2.0 Standard Extension API (including the
- <code>javax.sql.DataSource</code> API). This package is now known
- as the "JDBC Optional Package".</li>
- <li><a href="http://java.sun.com/j2ee/download.html">http://java.sun.com/j2ee/download.html</a> -
- The J2EE Platform Specification (covers the JDBC facilities that
- all J2EE platforms must provide to applications).</li>
- </ul>
-
- <p><strong>NOTE</strong> - The default data source support in Tomcat
- supports Tyrex. However, it is possible to use any other connection pool
- that implements <code>javax.sql.DataSource</code>, by writing your own
- custom resource factory, as described
- <a href="#Adding Custom Resource Factories">below</a>.</p>
-
- <h3>1. Install Your JDBC Driver</h3>
-
- <p>Use of the <em>JDBC Data Sources</em> JNDI Resource Factory requires
- that you make an appropriate JDBC driver available to both Tomcat internal
- classes and to your web application. This is most easily accomplished by
- installing the driver's JAR file(s) into the
- <code>$CATALINA_HOME/common/lib</code> directory, which makes the driver
- available both to the resource factory and to your application.</p>
-
- <h3>2. Declare Your Resource Requirements</h3>
-
- <p>Next, modify the web application deployment descriptor
- (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under
- which you will look up preconfigured data source. By convention, all such
- names should resolve to the <code>jdbc</code> subcontext (relative to the
- standard <code>java:comp/env</code> naming context that is the root of
- all provided resource factories. A typical <code>web.xml</code> entry
- might look like this:</p>
-<source>
-<resource-ref>
- <description>
- Resource reference to a factory for java.sql.Connection
- instances that may be used for talking to a particular
- database that is configured in the server.xml file.
- </description>
- <res-ref-name>
- jdbc/EmployeDB
- </res-ref-name>
- <res-type>
- javax.sql.DataSource
- </res-type>
- <res-auth>
- Container
- </res-auth>
-</resource-ref>
-</source>
-
- <p><strong>WARNING</strong> - Be sure you respect the element ordering
- that is required by the DTD for web application deployment descriptors!
- See the
- <a href="http://java.sun.com/products/servlet/download.html">Servlet
- Specification</a> for details.</p>
-
- <h3>3. Code Your Application's Use Of This Resource</h3>
-
- <p>A typical use of this resource reference might look like this:</p>
-<source>
-Context initCtx = new InitialContext();
-Context envCtx = (Context) initCtx.lookup("java:comp/env");
-DataSource ds = (DataSource)
- envCtx.lookup("jdbc/EmployeeDB");
-
-Connection conn = ds.getConnection();
-... use this connection to access the database ...
-conn.close();
-</source>
-
- <p>Note that the application uses the same resource reference name
- that was declared in the web application deployment descriptor. This
- is matched up against the resource factory that is configured in
- <code>$CATALINA_HOME/conf/server.xml</code>, as described below.</p>
-
- <h3>4. Configure Tomcat's Resource Factory</h3>
-
- <p>To configure Tomcat's resource factory, add an elements like this to the
- <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
- <code>Context</code> element for this web application (or nested inside
- a <code>DefaultContext</code> element for the surrounding
- <code><Host></code> or <code><Engine></code> element.</p>
-<source>
-<Context ...>
- ...
- <Resource name="jdbc/EmployeeDB" auth="Container"
- type="javax.sql.DataSource"/>
- <ResourceParams name="jdbc/EmployeeDB">
- <parameter>
- <name>user</name>
- <value>dbusername</value>
- </parameter>
- <parameter>
- <name>password</name>
- <value>dbpassword</value>
- </parameter>
- <parameter>
- <name>driverClassName</name>
- <value>org.hsql.jdbcDriver</value>
- </parameter>
- <parameter>
- <name>driverName</name>
- <value>jdbc:HypersonicSQL:database</value>
- </parameter>
- </ResourceParams>
- ...
-</Context>
-</source>
-
- <p>Note that the resource name (here, <code>jdbc/EmployeeDB</code>) must
- match the value specified in the web application deployment descriptor.
- Customize the value of the <code>mail.smtp.host</code> parameter to
- point at the server that provides SMTP service for your network.</p>
-
- <p>This example assumes that you are using the HypersonicSQL database
- JDBC driver. Customize the <code>driverClassName</code> and
- <code>driverName</code> parameters to match your actual database's
- JDBC driver and connection URL.</p>
-
- </subsection>
-
- <subsection name="User Transactions">
-
- <p>If you utilize Tyrex for your JDBC resource factory as described
- <a href="#JDBC Data Sources">above</a>, you will also have support for
- the <code>java.transaction.UserTransaction</code> resource provided by
- Tyrex (since it is XA-capable). To use this feature, code your
- application as follows:</p>
-<source>
-Context initCtx = new InitialContext();
-Context envCtx = (Context) initCtx.lookup("java:comp/env");
-Transaction tx = (Transaction) envCtx.lookup("UserTransaction");
-
-tx.begin();
-... perform transactional operations on data ...
-tx.commit();
-</source>
-
- <p>This is useful when you need to do "two-phased commits" across more
- than one database, where the commit needs to either succeed completely
- or fail completely across all associated databases. This feature
- requires a JDBC driver that also supports XA capabilities. See the
- J2EE and JDBC documentation for more information.</p>
-
- </subsection>
-
-</section>
-
-
-<section name="Adding Custom Resource Factories">
-
- <p>If none of the standard resource factories meet your needs, you can
- write your own factory and integrate it into Tomcat 4, and then configure
- the use of this factory in the <code>conf/server.xml</code> configuration
- file. In the example below, we will create a factory that only knows how
- to create <code>com.mycompany.MyBean</code> beans, from the
- <a href="Generic JavaBean Resources">Generic JavaBean Resources</a>
- example, above.</p>
-
- <h3>1. Write A Resource Factory Class</h3>
-
- <p>You must write a class that implements the JNDI service provider
- <code>javax.naming.spi.ObjectFactory</code> inteface. Every time your
- web application calls <code>lookup()</code> on a context entry that is
- bound to this factory, the <code>getObjectInstance()</code> method is
- called, with the following arguments:</p>
- <ul>
- <li><strong>Object obj</strong> - The (possibly null) object containing
- location or reference information that can be used in creating an
- object. For Tomcat, this will always be an object of type
- <code>javax.naming.Reference</code>, which contains the class name
- of this factory class, as well as the configuration properties
- (from <code>conf/server.xml</code>) to use in creating objects
- to be returned.</li>
- <li><strong>Name name</strong> - The name to which this factory is bound
- relative to <code>nameCtx</code>, or <code>null</code> if no name
- is specified.</li>
- <li><strong>Context nameCtx</strong> - The context relative to which the
- <code>name</code> parameter is specified, or <code>null</code> if
- <code>name</code> is relative to the default initial context.</li>
- <li><strong>Hashtable environment</strong> - The (possibly null)
- environment that is used in creating this object. This is generally
- ignored in Tomcat object factories.</li>
- </ul>
-
- <p>To create a resource factory that knows how to produce <code>MyBean</code>
- instances, you might create a class like this:</p>
-
-<source>
-package com.mycompany;
-
-import java.util.Enumeration;
-import java.util.Hashtable;
-import javax.naming.Context;
-import javax.naming.Name;
-import javax.naming.NamingException;
-import javax.naming.RefAddr;
-import javax.naming.Reference;
-import javax.naming.spi.ObjectFactory;
-
-public class MyBeanFactory implements ObjectFactory {
-
- public Object getObjectInstance(Object obj,
- Name name, Context nameCtx, Hashtable environment)
- throws NamingException {
-
- // Acquire an instance of our specified bean class
- MyBean bean = new MyBean();
-
- // Customize the bean properties from our attributes
- Reference ref = (Reference) obj;
- Enumeration addrs = ref.getAll();
- while (addrs.hasMoreElements()) {
- RefAddr addr = (RefAddr) addrs.nextElement();
- String name = addr.getType();
- String value = (String) addr.getContent();
- if (name.equals("foo")) {
- bean.setFoo(value);
- } else if (name.equals("bar")) {
- try {
- bean.setBar(Integer.parseInt(value));
- } catch (NumberFormatException e) {
- throw new NamingException("Invalid 'bar' value " + value);
- }
- }
- }
-
- // Return the customized instance
- return (bean);
-
- }
-
-}
-</source>
-
- <p>In this example, we are unconditionally creating a new instance of
- the <code>com.mycompany.MyBean</code> class, and populating its properties
- based on the parameters included in the <code><ResourceParams></code>
- element that configures this factory (see below). You should note that any
- parameter named <code>factory</code> should be skipped - that parameter is
- used to specify the name of the factory class itself (in this case,
- <code>com.mycompany.MyBeanFactory</code>) rather than a property of the
- bean being configured.</p>
-
- <p>For more information about <code>ObjectFactory</code>, see the
- <a href="http://java.sun.com/products/jndi/docs.html">JNDI 1.2 Service
- Provider Interface (SPI) Specification</a>.</p>
-
- <p>You will need to compile this class against a class path that includes
- all of the JAR files in the <code>$CATALINA_HOME/common/lib</code> and
- <code>$CATALINA_HOME/server/lib</code> directories. When you are through,
- place the factory class (and the corresponding bean class) unpacked under
- <code>$CATALINA_HOME/common/classes</code>, or in a JAR file inside
- <code>$CATALINA_HOME/common/lib</code>. In this way, the required class
- files are visible to both Catalina internal resources and your web
- application.</p>
-
- <h3>2. Declare Your Resource Requirements</h3>
-
- <p>Next, modify your web application deployment descriptor
- (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which
- you will request new instances of this bean. The simplest approach is
- to use a <code><resource-env-ref></code> element, like this:</p>
-
-<source>
-<resource-env-ref>
- <description>
- Object factory for MyBean instances.
- </description>
- <resource-env-ref-name>
- bean/MyBeanFactory
- </resource-env-ref-name>
- <resource-env-ref-type>
- com.mycompany.MyBean
- </resource-env-ref-type>
-<resource-env-ref>
-</source>
-
- <p><strong>WARNING</strong> - Be sure you respect the element ordering
- that is required by the DTD for web application deployment descriptors!
- See the
- <a href="http://java.sun.com/products/servlet/download.html">Servlet
- Specification</a> for details.</p>
-
- <h3>3. Code Your Application's Use Of This Resource</h3>
-
- <p>A typical use of this resource environment reference might look
- like this:</p>
-
-<source>
-Context initCtx = new InitialContext();
-Context envCtx = (Context) initCtx.lookup("java:comp/env");
-MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");
-
-writer.println("foo = " + bean.getFoo() + ", bar = " +
- bean.getBar());
-</source>
-
- <h3>4. Configure Tomcat's Resource Factory</h3>
-
- <p>To configure Tomcat's resource factory, add an elements like this to the
- <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
- <code>Context</code> element for this web application (or nested inside
- a <code>DefaultContext</code> element for the surrounding
- <code><Host></code> or <code><Engine></code> element.</p>
-<source>
-<Context ...>
- ...
- <Resource name="bean/MyBeanFactory" auth="Container"
- type="com.mycompany.MyBean"/>
- <ResourceParams name="bean/MyBeanFactory">
- <parameter>
- <name>factory</name>
- <value>com.mycompany.MyBeanFactory</value>
- </parameter>
- <parameter>
- <name>bar</name>
- <value>23</value>
- </parameter>
- </ResourceParams>
- ...
-</Context>
-</source>
-
- <p>Note that the resource name (here, <code>bean/MyBeanFactory</code>
- must match the value specified in the web application deployment
- descriptor. We are also initializing the value of the <code>bar</code>
- property, which will cause <code>setBar(23)</code> to be called before
- the new bean is returned. Because we are not initializing the
- <code>foo</code> property (although we could have), the bean will
- contain whatever default value is set up by its constructor.</p>
-
- <p>You will also note that, from the application developer's perspective,
- the declaration of the resource environment reference, and the programming
- used to request new instances, is identical to the approach used for the
- <em>Generic JavaBean Resources</em> example. This illustrates one of the
- advantages of using JNDI resources to encapsulate functionality - you can
- change the underlying implementation without necessarily having to
- modify applications using the resources, as long as you maintain
- compatible APIs.</p>
-
-</section>
-
-
-
-</body>
-
-</document>
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document>
+
+ &project;
+
+ <properties>
+ <author email="craigmcc@apache.org">Craig R. McClanahan</author>
+ <title>JNDI Resources HOW-TO</title>
+ </properties>
+
+<body>
+
+
+<section name="Introduction">
+
+<p>Tomcat 4 provides a JNDI <strong>InitialContext</strong> implementation
+instance to web applications running under it, in a manner that is compatible
+with those provided by a <a href="http://java.sun.com/j2ee">Java2 Enterprise
+Edition</a> application server. Entries in this <code>InitialContext</code>
+are configured in the <code>$CATALINA_HOME/conf/server.xml</code> file, and
+may be referenced by the following elements in the web application deployment
+descriptor (<code>/WEB-INF/web.xml</code>) of your web application:</p>
+<ul>
+<li><code><strong><env-entry></strong></code> - Environment entry, a
+ single-value parameter that can be used to configure how the application
+ will operate.</li>
+<li><code><strong><resource-ref></strong></code> - Resource reference,
+ which is typically to an object factory for resources such as a JDBC
+ <code>DataSource</code>, a JavaMail <code>Session</code>, or custom
+ object factories configured into Tomcat 4.</li>
+<li><code><strong><resource-env-ref></strong></code> - Resource
+ environment reference, a new variation of <code>resource-ref</code>
+ added in Servlet 2.3 that is simpler to configure for resources
+ that do not require authentication information.</li>
+</ul>
+
+<p>The <code>InitialContext</code> is configured as a web application is
+initially deployed, and is made available to web application components (for
+read-only access). All configured entries and resources will be placed in
+the <code>java:comp/env</code> portion of the JNDI namespace, so a typical
+access to a resource - in this case, to a JDBC <code>DataSource</code> -
+would look something like this:</p>
+<source>
+// Obtain our environment naming context
+Context initCtx = new InitialContext();
+Context envCtx = (Context) initCtx.lookup("java:comp/env");
+
+// Look up our data source
+DataSource ds = (DataSource)
+ envCtx.lookup("jdbc/EmployeeDB");
+
+// Allocate and use a connection from the pool
+Connection conn = ds.getConnection();
+... use this connection to access the database ...
+conn.close();
+</source>
+
+<p>See the following Specifications for more information about programming APIs
+for JNDI, and for the features supported by Java2 Enterprise Edition (J2EE)
+servers, which Tomcat emulates for the services that it provides:</p>
+<ul>
+<li><a href="http://java.sun.com/products/jndi/#download">Java Naming and
+ Directory Interface</a> (included in JDK 1.4, available separately for
+ prior JDK versions)</li>
+<li><a href="http://java.sun.com/j2ee/download.html">J2EE Platform
+ Specification</a> (in particular, see Chapter 5 on <em>Naming</em>)</li>
+</ul>
+
+</section>
+
+
+<section name="Configuring JNDI Resources">
+
+<p>Each available JNDI Resource is configured based on inclusion of the
+following elements in the <code>$CATALINA_HOME/conf/server.xml</code>
+file:</p>
+<ul>
+<li><a href="config/context.html#Environment Entries"><Environment></a> -
+ Configure names and values for scalar environment entries that will be
+ exposed to the web application through the JNDI
+ <code>InitialContext</code> (equivalent to the inclusion of an
+ <code><env-entry></code> element in the web application
+ deployment descriptor).</li>
+<li><a href="config/context.html#Resource Definitions"><Resource></a> -
+ Configure the name and data type of a resource made available to the
+ application (equivalent to the inclusion of a
+ <code><resource-ref></code> element in the web application
+ deployment descriptor).</li>
+<li><a href="config/context.html#Resource Parameters"><ResourceParams></a> -
+ Configure the Java class name of the resource factory implementation to be
+ used, as well as JavaBeans properties used to configure that resource
+ factory.</li>
+</ul>
+
+<p>Any number of these elements may be nested inside a
+<a href="config/context.html"><Context></a> element (to be associated
+only with that particular web application) or inside a
+<a href="config/defaultcontext.html"><DefaultContext></a> element
+(used to set the default configuration characteristics for automatically
+deloyed applications).</p>
+
+<p>In addition, the names and values of all <code><env-entry></code>
+elements included in the web application deployment descriptor
+(<code>/WEB-INF/web.xml</code>) are configured into the initial context as
+well, overriding corresponding values from <code>conf/server.xml</code>
+<strong>only</strong> if allowed by the corresponding
+<code><Environment></code> element (by setting the
+<code>override</code> attribute to "true").</p>
+
+</section>
+
+
+<section name="Tomcat Standard Resource Factories">
+
+ <p>Tomcat 4 includes a series of standard resource factories that can
+ provide services to your web applications, but give you configuration
+ flexibility (in <code>$CATALINA_HOME/conf/server.xml</code>) without
+ modifying the web application or the deployment descriptor. Each
+ subsection below details the configuration and usage of the standard
+ resource factories.</p>
+
+ <p>See <a href="#Adding Custom Resource Factories">Adding Custom
+ Resource Factories</a> for information about how to create, install,
+ configure, and use your own custom resource factory classes with
+ Tomcat 4.</p>
+
+ <p><em>NOTE</em> - Of the standard resource factories, only the
+ "JDBC Data Source" and "User Transaction" factories are mandated to
+ be available on other platforms, and then they are required only if
+ the platform implements the Java2 Enterprise Edition (J2EE) specs.
+ All other standard resource factories, plus custom resource factories
+ that you write yourself, are specific to Tomcat and cannot be assumed
+ to be available on other containers.</p>
+
+ <subsection name="Generic JavaBean Resources">
+
+ <h3>0. Introduction</h3>
+
+ <p>This resource factory can be used to create objects of <em>any</em>
+ Java class that conforms to standard JavaBeans naming conventions (i.e.
+ it has a zero-arguments constructor, and has property setters that
+ conform to the setFoo() naming pattern. The resource factory will
+ create a new instance of the appropriate bean class every time a
+ <code>lookup()</code> for this entry is made.</p>
+
+ <p>The steps required to use this facility are described below.</p>
+
+ <h3>1. Create Your JavaBean Class</h3>
+
+ <p>Create the JavaBean class which will be instantiated each time
+ that the resource factory is looked up. For this example, assume
+ you create a class <code>com.mycompany.MyBean</code>, which looks
+ like this:</p>
+
+<source>
+package com.mycompany;
+
+public class MyBean {
+
+ private String foo = "Default Foo";
+
+ public String getFoo() {
+ return (this.foo);
+ }
+
+ public void setFoo(String foo) {
+ this.foo = foo;
+ }
+
+ private int bar = 0;
+
+ public int getBar() {
+ return (this.bar);
+ }
+
+ public void setBar(int bar) {
+ this.bar = bar;
+ }
+
+
+}
+</source>
+
+ <h3>2. Declare Your Resource Requirements</h3>
+
+ <p>Next, modify your web application deployment descriptor
+ (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which
+ you will request new instances of this bean. The simplest approach is
+ to use a <code><resource-env-ref></code> element, like this:</p>
+
+<source>
+<resource-env-ref>
+ <Description>
+ Object factory for MyBean instances.
+ </Description>
+ <resource-env-ref-name>
+ bean/MyBeanFactory
+ </resource-env-ref-name>
+ <resource-env-ref-type>
+ com.mycompany.MyBean
+ </resource-env-ref-type>
+<resource-env-ref>
+</source>
+
+ <p><strong>WARNING</strong> - Be sure you respect the element ordering
+ that is required by the DTD for web application deployment descriptors!
+ See the
+ <a href="http://java.sun.com/products/servlet/download.html">Servlet
+ Specification</a> for details.</p>
+
+ <h3>3. Code Your Application's Use Of This Resource</h3>
+
+ <p>A typical use of this resource environment reference might look
+ like this:</p>
+
+<source>
+Context initCtx = new InitialContext();
+Context envCtx = (Context) initCtx.lookup("java:comp/env");
+MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");
+
+writer.println("foo = " + bean.getFoo() + ", bar = " +
+ bean.getBar());
+</source>
+
+ <h3>4. Configure Tomcat's Resource Factory</h3>
+
+ <p>To configure Tomcat's resource factory, add an elements like this to the
+ <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
+ <code>Context</code> element for this web application (or nested inside
+ a <code>DefaultContext</code> element for the surrounding
+ <code><Host></code> or <code><Engine></code> element.</p>
+<source>
+<Context ...>
+ ...
+ <Resource name="bean/MyBeanFactory" auth="Container"
+ type="com.mycompany.MyBean"/>
+ <ResourceParams name="bean/MyBeanFactory">
+ <parameter>
+ <name>factory</name>
+ <value>org.apache.naming.factory.BeanFactory</value>
+ </parameter>
+ <parameter>
+ <name>bar</name>
+ <value>23</value>
+ </parameter>
+ </ResourceParams>
+ ...
+</Context>
+</source>
+
+ <p>Note that the resource name (here, <code>bean/MyBeanFactory</code>
+ must match the value specified in the web application deployment
+ descriptor. We are also initializing the value of the <code>bar</code>
+ property, which will cause <code>setBar(23)</code> to be called before
+ the new bean is returned. Because we are not initializing the
+ <code>foo</code> property (although we could have), the bean will
+ contain whatever default value is set up by its constructor.</p>
+
+ </subsection>
+
+
+ <subsection name="JavaMail Sessions">
+
+ <h3>0. Introduction</h3>
+
+ <p>In many web applications, sending electronic mail messages is a
+ required part of the system's functionality. The
+ <a href="http://java.sun.com/products/javamail">Java Mail</a> API
+ makes this process relatively straightforward, but requires many
+ configuration details that the client application must be aware of
+ (including the name of the SMTP host to be used for message sending).</p>
+
+ <p>Tomcat 4 includes a standard resource factory that will create
+ <code>javax.mail.Session</code> session instances for you, already
+ connected to the SMTP server that is configured in <code>server.xml</code>.
+ In this way, the application is totally insulated from changes in the
+ email server configuration environment - it simply asks for, and receives,
+ a preconfigured session whenever needed.</p>
+
+ <p>The steps required for this are outlined below.</p>
+
+ <h3>1. Declare Your Resource Requirements</h3>
+
+ <p>The first thing you should do is modify the web application deployment
+ descriptor (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under
+ which you will look up preconfigured sessions. By convention, all such
+ names should resolve to the <code>mail</code> subcontext (relative to the
+ standard <code>java:comp/env</code> naming context that is the root of
+ all provided resource factories. A typical <code>web.xml</code> entry
+ might look like this:</p>
+<source>
+<resource-ref>
+ <description>
+ Resource reference to a factory for javax.mail.Session
+ instances that may be used for sending electronic mail
+ messages, preconfigured to connect to the appropriate
+ SMTP server.
+ </description>
+ <res-ref-name>
+ mail/Session
+ </res-ref-name>
+ <res-type>
+ javax.mail.Session
+ </res-type>
+ <res-auth>
+ Container
+ </res-auth>
+</resource-ref>
+</source>
+
+ <p><strong>WARNING</strong> - Be sure you respect the element ordering
+ that is required by the DTD for web application deployment descriptors!
+ See the
+ <a href="http://java.sun.com/products/servlet/download.html">Servlet
+ Specification</a> for details.</p>
+
+ <h3>2. Code Your Application's Use Of This Resource</h3>
+
+ <p>A typical use of this resource reference might look like this:</p>
+<source>
+Context initCtx = new InitialContext();
+Context envCtx = (Context) initCtx.lookup("java:comp/env");
+Session session = (Session) envCtx.lookup("mail/Session");
+
+Message message = new MimeMessage(session);
+message.setFrom(new InternetAddress(request.getParameter("from"));
+InternetAddress to[] = new InternetAddress[1];
+to[0] = new InternetAddress(request.getParameter("to"));
+message.setRecipients(Message.RecipientType.TO, to);
+message.setSubject(request.getParameter("subject"));
+message.setContent(request.getParameter("content"), "text/plain");
+Transport.send(message);
+</source>
+
+ <p>Note that the application uses the same resource reference name
+ that was declared in the web application deployment descriptor. This
+ is matched up against the resource factory that is configured in
+ <code>$CATALINA_HOME/conf/server.xml</code>, as described below.</p>
+
+ <h3>3. Configure Tomcat's Resource Factory</h3>
+
+ <p>To configure Tomcat's resource factory, add an elements like this to the
+ <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
+ <code>Context</code> element for this web application (or nested inside
+ a <code>DefaultContext</code> element for the surrounding
+ <code><Host></code> or <code><Engine></code> element.</p>
+<source>
+<Context ...>
+ ...
+ <Resource name="mail/Session" auth="Container"
+ type="javax.mail.Session"/>
+ <ResourceParams name="mail/Session">
+ <parameter>
+ <name>mail.smtp.host</name>
+ <value>localhost</value>
+ </parameter>
+ </ResourceParams>
+ ...
+</Context>
+</source>
+
+ <p>Note that the resource name (here, <code>mail/Session</code>) must
+ match the value specified in the web application deployment descriptor.
+ Customize the value of the <code>mail.smtp.host</code> parameter to
+ point at the server that provides SMTP service for your network.</p>
+
+ <h3>Example Application</h3>
+
+ <p>The <code>/examples</code> application included with Tomcat contains
+ an example of utilizing this resource factory. It is accessed via the
+ "JSP Examples" link. The source code for the servlet that actually
+ sends the mail message is in
+ <code>/WEB-INF/classes/SendMailServlet.java</code>.</p>
+
+ <p><strong>WARNING</strong> - The default configuration assumes that
+ there is an SMTP server listing on port 25 on <code>localhost</code>.
+ If this is not the case, edit the
+ <code>$CATALINA_HOME/conf/server.xml</code> file, and modify the
+ parameter value for the <code>mail.smtp.host</code> parameter to be
+ the host name of an SMTP server on your network.</p>
+
+ </subsection>
+
+ <subsection name="JDBC Data Sources">
+
+ <h3>0. Introduction</h3>
+
+ <p>Many web applications need to access a database via a JDBC driver,
+ to support the functionality required by that application. The J2EE
+ Platform Specification requires J2EE Application Servers to make
+ available a <em>DataSource</em> implementation (that is, a connection
+ pool for JDBC connections) for this purpose. Tomcat 4 offers exactly
+ the same support, so that database-based applications you develop on
+ Tomcat using this service will run unchanged on any J2EE server.</p>
+
+ <p>For information about JDBC, you should consult the following:</p>
+ <ul>
+ <li><a href="http://java.sun.com/products/jdbc/">http://java.sun.com/products/jdbc/</a> -
+ Home page for information about Java Database Connectivity.</li>
+ <li><a href="http://java.sun.com/j2se/1.3/docs/guide/jdbc/spec2/jdbc2.1.frame.html">http://java.sun.com/j2se/1.3/docs/guide/jdbc/spec2/jdbc2.1.frame.html</a> -
+ The JDBC 2.1 API Specification.</li>
+ <li><a href="http://java.sun.com/products/jdbc/jdbc20.stdext.pdf">http://java.sun.com/products/jdbc/jdbc20.stdext.pdf</a> -
+ The JDBC 2.0 Standard Extension API (including the
+ <code>javax.sql.DataSource</code> API). This package is now known
+ as the "JDBC Optional Package".</li>
+ <li><a href="http://java.sun.com/j2ee/download.html">http://java.sun.com/j2ee/download.html</a> -
+ The J2EE Platform Specification (covers the JDBC facilities that
+ all J2EE platforms must provide to applications).</li>
+ </ul>
+
+ <p><strong>NOTE</strong> - The default data source support in Tomcat
+ supports Tyrex. However, it is possible to use any other connection pool
+ that implements <code>javax.sql.DataSource</code>, by writing your own
+ custom resource factory, as described
+ <a href="#Adding Custom Resource Factories">below</a>.</p>
+
+ <h3>1. Install Your JDBC Driver</h3>
+
+ <p>Use of the <em>JDBC Data Sources</em> JNDI Resource Factory requires
+ that you make an appropriate JDBC driver available to both Tomcat internal
+ classes and to your web application. This is most easily accomplished by
+ installing the driver's JAR file(s) into the
+ <code>$CATALINA_HOME/common/lib</code> directory, which makes the driver
+ available both to the resource factory and to your application.</p>
+
+ <h3>2. Declare Your Resource Requirements</h3>
+
+ <p>Next, modify the web application deployment descriptor
+ (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under
+ which you will look up preconfigured data source. By convention, all such
+ names should resolve to the <code>jdbc</code> subcontext (relative to the
+ standard <code>java:comp/env</code> naming context that is the root of
+ all provided resource factories. A typical <code>web.xml</code> entry
+ might look like this:</p>
+<source>
+<resource-ref>
+ <description>
+ Resource reference to a factory for java.sql.Connection
+ instances that may be used for talking to a particular
+ database that is configured in the server.xml file.
+ </description>
+ <res-ref-name>
+ jdbc/EmployeDB
+ </res-ref-name>
+ <res-type>
+ javax.sql.DataSource
+ </res-type>
+ <res-auth>
+ Container
+ </res-auth>
+</resource-ref>
+</source>
+
+ <p><strong>WARNING</strong> - Be sure you respect the element ordering
+ that is required by the DTD for web application deployment descriptors!
+ See the
+ <a href="http://java.sun.com/products/servlet/download.html">Servlet
+ Specification</a> for details.</p>
+
+ <h3>3. Code Your Application's Use Of This Resource</h3>
+
+ <p>A typical use of this resource reference might look like this:</p>
+<source>
+Context initCtx = new InitialContext();
+Context envCtx = (Context) initCtx.lookup("java:comp/env");
+DataSource ds = (DataSource)
+ envCtx.lookup("jdbc/EmployeeDB");
+
+Connection conn = ds.getConnection();
+... use this connection to access the database ...
+conn.close();
+</source>
+
+ <p>Note that the application uses the same resource reference name
+ that was declared in the web application deployment descriptor. This
+ is matched up against the resource factory that is configured in
+ <code>$CATALINA_HOME/conf/server.xml</code>, as described below.</p>
+
+ <h3>4. Configure Tomcat's Resource Factory</h3>
+
+ <p>To configure Tomcat's resource factory, add an elements like this to the
+ <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
+ <code>Context</code> element for this web application (or nested inside
+ a <code>DefaultContext</code> element for the surrounding
+ <code><Host></code> or <code><Engine></code> element.</p>
+<source>
+<Context ...>
+ ...
+ <Resource name="jdbc/EmployeeDB" auth="Container"
+ type="javax.sql.DataSource"/>
+ <ResourceParams name="jdbc/EmployeeDB">
+ <parameter>
+ <name>user</name>
+ <value>dbusername</value>
+ </parameter>
+ <parameter>
+ <name>password</name>
+ <value>dbpassword</value>
+ </parameter>
+ <parameter>
+ <name>driverClassName</name>
+ <value>org.hsql.jdbcDriver</value>
+ </parameter>
+ <parameter>
+ <name>driverName</name>
+ <value>jdbc:HypersonicSQL:database</value>
+ </parameter>
+ </ResourceParams>
+ ...
+</Context>
+</source>
+
+ <p>Note that the resource name (here, <code>jdbc/EmployeeDB</code>) must
+ match the value specified in the web application deployment descriptor.
+ Customize the value of the <code>mail.smtp.host</code> parameter to
+ point at the server that provides SMTP service for your network.</p>
+
+ <p>This example assumes that you are using the HypersonicSQL database
+ JDBC driver. Customize the <code>driverClassName</code> and
+ <code>driverName</code> parameters to match your actual database's
+ JDBC driver and connection URL.</p>
+
+ </subsection>
+
+ <subsection name="User Transactions">
+
+ <p>If you utilize Tyrex for your JDBC resource factory as described
+ <a href="#JDBC Data Sources">above</a>, you will also have support for
+ the <code>java.transaction.UserTransaction</code> resource provided by
+ Tyrex (since it is XA-capable). To use this feature, code your
+ application as follows:</p>
+<source>
+Context initCtx = new InitialContext();
+Context envCtx = (Context) initCtx.lookup("java:comp/env");
+Transaction tx = (Transaction) envCtx.lookup("UserTransaction");
+
+tx.begin();
+... perform transactional operations on data ...
+tx.commit();
+</source>
+
+ <p>This is useful when you need to do "two-phased commits" across more
+ than one database, where the commit needs to either succeed completely
+ or fail completely across all associated databases. This feature
+ requires a JDBC driver that also supports XA capabilities. See the
+ J2EE and JDBC documentation for more information.</p>
+
+ </subsection>
+
+</section>
+
+
+<section name="Adding Custom Resource Factories">
+
+ <p>If none of the standard resource factories meet your needs, you can
+ write your own factory and integrate it into Tomcat 4, and then configure
+ the use of this factory in the <code>conf/server.xml</code> configuration
+ file. In the example below, we will create a factory that only knows how
+ to create <code>com.mycompany.MyBean</code> beans, from the
+ <a href="Generic JavaBean Resources">Generic JavaBean Resources</a>
+ example, above.</p>
+
+ <h3>1. Write A Resource Factory Class</h3>
+
+ <p>You must write a class that implements the JNDI service provider
+ <code>javax.naming.spi.ObjectFactory</code> inteface. Every time your
+ web application calls <code>lookup()</code> on a context entry that is
+ bound to this factory, the <code>getObjectInstance()</code> method is
+ called, with the following arguments:</p>
+ <ul>
+ <li><strong>Object obj</strong> - The (possibly null) object containing
+ location or reference information that can be used in creating an
+ object. For Tomcat, this will always be an object of type
+ <code>javax.naming.Reference</code>, which contains the class name
+ of this factory class, as well as the configuration properties
+ (from <code>conf/server.xml</code>) to use in creating objects
+ to be returned.</li>
+ <li><strong>Name name</strong> - The name to which this factory is bound
+ relative to <code>nameCtx</code>, or <code>null</code> if no name
+ is specified.</li>
+ <li><strong>Context nameCtx</strong> - The context relative to which the
+ <code>name</code> parameter is specified, or <code>null</code> if
+ <code>name</code> is relative to the default initial context.</li>
+ <li><strong>Hashtable environment</strong> - The (possibly null)
+ environment that is used in creating this object. This is generally
+ ignored in Tomcat object factories.</li>
+ </ul>
+
+ <p>To create a resource factory that knows how to produce <code>MyBean</code>
+ instances, you might create a class like this:</p>
+
+<source>
+package com.mycompany;
+
+import java.util.Enumeration;
+import java.util.Hashtable;
+import javax.naming.Context;
+import javax.naming.Name;
+import javax.naming.NamingException;
+import javax.naming.RefAddr;
+import javax.naming.Reference;
+import javax.naming.spi.ObjectFactory;
+
+public class MyBeanFactory implements ObjectFactory {
+
+ public Object getObjectInstance(Object obj,
+ Name name, Context nameCtx, Hashtable environment)
+ throws NamingException {
+
+ // Acquire an instance of our specified bean class
+ MyBean bean = new MyBean();
+
+ // Customize the bean properties from our attributes
+ Reference ref = (Reference) obj;
+ Enumeration addrs = ref.getAll();
+ while (addrs.hasMoreElements()) {
+ RefAddr addr = (RefAddr) addrs.nextElement();
+ String name = addr.getType();
+ String value = (String) addr.getContent();
+ if (name.equals("foo")) {
+ bean.setFoo(value);
+ } else if (name.equals("bar")) {
+ try {
+ bean.setBar(Integer.parseInt(value));
+ } catch (NumberFormatException e) {
+ throw new NamingException("Invalid 'bar' value " + value);
+ }
+ }
+ }
+
+ // Return the customized instance
+ return (bean);
+
+ }
+
+}
+</source>
+
+ <p>In this example, we are unconditionally creating a new instance of
+ the <code>com.mycompany.MyBean</code> class, and populating its properties
+ based on the parameters included in the <code><ResourceParams></code>
+ element that configures this factory (see below). You should note that any
+ parameter named <code>factory</code> should be skipped - that parameter is
+ used to specify the name of the factory class itself (in this case,
+ <code>com.mycompany.MyBeanFactory</code>) rather than a property of the
+ bean being configured.</p>
+
+ <p>For more information about <code>ObjectFactory</code>, see the
+ <a href="http://java.sun.com/products/jndi/docs.html">JNDI 1.2 Service
+ Provider Interface (SPI) Specification</a>.</p>
+
+ <p>You will need to compile this class against a class path that includes
+ all of the JAR files in the <code>$CATALINA_HOME/common/lib</code> and
+ <code>$CATALINA_HOME/server/lib</code> directories. When you are through,
+ place the factory class (and the corresponding bean class) unpacked under
+ <code>$CATALINA_HOME/common/classes</code>, or in a JAR file inside
+ <code>$CATALINA_HOME/common/lib</code>. In this way, the required class
+ files are visible to both Catalina internal resources and your web
+ application.</p>
+
+ <h3>2. Declare Your Resource Requirements</h3>
+
+ <p>Next, modify your web application deployment descriptor
+ (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which
+ you will request new instances of this bean. The simplest approach is
+ to use a <code><resource-env-ref></code> element, like this:</p>
+
+<source>
+<resource-env-ref>
+ <description>
+ Object factory for MyBean instances.
+ </description>
+ <resource-env-ref-name>
+ bean/MyBeanFactory
+ </resource-env-ref-name>
+ <resource-env-ref-type>
+ com.mycompany.MyBean
+ </resource-env-ref-type>
+<resource-env-ref>
+</source>
+
+ <p><strong>WARNING</strong> - Be sure you respect the element ordering
+ that is required by the DTD for web application deployment descriptors!
+ See the
+ <a href="http://java.sun.com/products/servlet/download.html">Servlet
+ Specification</a> for details.</p>
+
+ <h3>3. Code Your Application's Use Of This Resource</h3>
+
+ <p>A typical use of this resource environment reference might look
+ like this:</p>
+
+<source>
+Context initCtx = new InitialContext();
+Context envCtx = (Context) initCtx.lookup("java:comp/env");
+MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");
+
+writer.println("foo = " + bean.getFoo() + ", bar = " +
+ bean.getBar());
+</source>
+
+ <h3>4. Configure Tomcat's Resource Factory</h3>
+
+ <p>To configure Tomcat's resource factory, add an elements like this to the
+ <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
+ <code>Context</code> element for this web application (or nested inside
+ a <code>DefaultContext</code> element for the surrounding
+ <code><Host></code> or <code><Engine></code> element.</p>
+<source>
+<Context ...>
+ ...
+ <Resource name="bean/MyBeanFactory" auth="Container"
+ type="com.mycompany.MyBean"/>
+ <ResourceParams name="bean/MyBeanFactory">
+ <parameter>
+ <name>factory</name>
+ <value>com.mycompany.MyBeanFactory</value>
+ </parameter>
+ <parameter>
+ <name>bar</name>
+ <value>23</value>
+ </parameter>
+ </ResourceParams>
+ ...
+</Context>
+</source>
+
+ <p>Note that the resource name (here, <code>bean/MyBeanFactory</code>
+ must match the value specified in the web application deployment
+ descriptor. We are also initializing the value of the <code>bar</code>
+ property, which will cause <code>setBar(23)</code> to be called before
+ the new bean is returned. Because we are not initializing the
+ <code>foo</code> property (although we could have), the bean will
+ contain whatever default value is set up by its constructor.</p>
+
+ <p>You will also note that, from the application developer's perspective,
+ the declaration of the resource environment reference, and the programming
+ used to request new instances, is identical to the approach used for the
+ <em>Generic JavaBean Resources</em> example. This illustrates one of the
+ advantages of using JNDI resources to encapsulate functionality - you can
+ change the underlying implementation without necessarily having to
+ modify applications using the resources, as long as you maintain
+ compatible APIs.</p>
+
+</section>
+
+
+
+</body>
+
+</document>
1.1.2.1 +129 -129 jakarta-tomcat-4.0/webapps/tomcat-docs/proxy-howto.xml
Index: proxy-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/proxy-howto.xml,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- proxy-howto.xml 21 Aug 2001 02:28:21 -0000 1.1
+++ proxy-howto.xml 26 Mar 2002 14:18:44 -0000 1.1.2.1
@@ -1,129 +1,129 @@
-<?xml version="1.0"?>
-<!DOCTYPE document [
- <!ENTITY project SYSTEM "project.xml">
-]>
-<document>
-
- &project;
-
- <properties>
- <author email="craigmcc@apache.org">Craig R. McClanahan</author>
- <title>Proxy Support HOW-TO</title>
- </properties>
-
-<body>
-
-
-<section name="Introduction">
-
-<p>Using standard configurations of Tomcat, web applications can ask for
-the server name and port number to which the request was directed for
-processing. When Tomcat is running standalone with the
-<a href="config/http11.html">HTTP/1.1 Connector</a>, it will generally
-report the server name specified in the request, and the port number on
-which the <strong>Connector</strong> is listening. The two servlet API
-calls of interest, for this purpose, are:</p>
-<ul>
-<li><code>ServletRequest.getServerName()</code></li>
-<li><code>ServletRequest.getServerPort()</code></li>
-</ul>
-
-<p>When you are running behind a proxy server (or a web server that is
-configured to behave like a proxy server), you will sometimes prefer to
-manage the values returned by these calls. In particular, you will
-generally want the port number to reflect that specified in the original
-request, not the one on which the <strong>Connector</strong> itself is
-listening. You can use the <code>proxyName</code> and <code>proxyPort</code>
-attributes on the <code><Connector></code> element to configure
-these values.</p>
-
-<p>Proxy support can take many forms. The following sections describe
-proxy configurations for several common cases.</p>
-
-</section>
-
-<section name="Apache 1.3 Proxy Support">
-
-<p>Apache 1.3 supports an optional module (<code>mod_proxy</code>) that
-configures the web server to act as a proxy server. This can be used to
-forward requests for a particular web application to a Tomcat 4 instance,
-without having to configure a web connector such as <code>mod_webapp</code>.
-To accomplish this, you need to perform the following tasks:</p>
-<ol>
-<li>Configure your copy of Apache so that it includes the
- <code>mod_proxy</code> module. If you are building from source,
- the easiest way to do this is to include the
- <code>--enable-module=proxy</code> directive on the
- <code>./configure</code> command line.</li>
-<li>If not already added for you, make sure that you are loading the
- <code>mod_proxy</code> module at Apache startup time, by using the
- following directives in your <code>httpd.conf</code> file:
-<source>
-LoadModule proxy_module {path-to-modules}/mod_proxy.so
-AddModule mod_proxy.c
-</source></li>
-<li>Include two directives in your <code>httpd.conf</code> file for
- each web application that you wish to forward to Tomcat 4. For
- example, to forward an application at context path <code>/myapp</code>:
-<source>
-ProxyPass /myapp http://localhost:8081/myapp
-ProxyPassReverse /myapp http://localhost:8081/myapp
-</source>
- which tells Apache to forward URLs of the form
- <code>http://localhost/myapp/*</code> to the Tomcat 4 connector
- listening on port 8081.</li>
-<li>Configure your copy of Tomcat 4 to include a special
- <code><Connector></code> element, with appropriate
- proxy settings, for example:
-<source>
-<Connector className="org.apache.catalina.connector.http.HttpConnector"
- port="8081" ...
- proxyName="www.mycompany.com"
- proxyPort="80"/>
-</source>
- which will cause servlets inside this web application to think that
- all proxied requests were directed to <code>www.mycompany.com</code>
- on port 80.</li>
-<li>It is legal to omit the <code>proxyName</code> attribute from the
- <code><Connector></code> element. If you do so, the value
- returned by <code>request.getServerName()</code> will by the host
- name on which Tomcat is running. In the example above, it would be
- <code>localhost</code>.</li>
-<li>If you also have a <code><Connector></code> listening on port
- 8080 (nested within the same <a href="config/service.html">Service</a>
- element), the requests to either port will share the same set of
- virtual hosts and web applications.</li>
-<li>You might wish to use the IP filtering features of your operating
- system to restrict connections to port 8081 (in this example) to
- be allowed <strong>only</strong> from the server that is running
- Apache.</li>
-<li>Alternatively, you can set up a series of web applications that are
- only available via proxying, as follows:
- <ul>
- <li>Configure another <code><Service></code> that contains
- only a <code><Connector></code> for the proxy port.</li>
- <li>Configure appropriate <a href="config/engine.html">Engine</a>,
- <a href="host.html">Host</a>, and
- <a href="context.html">Context</a> elements for the virtual hosts
- and web applications accessible via proxying.</li>
- <li>Optionally, protect port 8081 with IP filters as described
- earlier.</li>
- </ul></li>
-<li>When requests are proxied by Apache, the web server will be recording
- these requests in its access log. Therefore, you will generally want to
- disable any access logging performed by Tomcat itself.</li>
-</ol>
-
-<p>When requests are proxied in this manner, <strong>all</strong> requests
-for the configured web applications will be processed by Tomcat (including
-requests for static content). You will often be able to improve performance
-by using the <code>mod_webapp</code> web connector instead, which
-automatically configures itself to have Apache handle static content that is
-not processed by filters or security constraints defined within the web
-application's deployment descriptor (<code>/WEB-INF/web.xml</code>).</p>
-
-</section>
-
-</body>
-
-</document>
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document>
+
+ &project;
+
+ <properties>
+ <author email="craigmcc@apache.org">Craig R. McClanahan</author>
+ <title>Proxy Support HOW-TO</title>
+ </properties>
+
+<body>
+
+
+<section name="Introduction">
+
+<p>Using standard configurations of Tomcat, web applications can ask for
+the server name and port number to which the request was directed for
+processing. When Tomcat is running standalone with the
+<a href="config/http11.html">HTTP/1.1 Connector</a>, it will generally
+report the server name specified in the request, and the port number on
+which the <strong>Connector</strong> is listening. The two servlet API
+calls of interest, for this purpose, are:</p>
+<ul>
+<li><code>ServletRequest.getServerName()</code></li>
+<li><code>ServletRequest.getServerPort()</code></li>
+</ul>
+
+<p>When you are running behind a proxy server (or a web server that is
+configured to behave like a proxy server), you will sometimes prefer to
+manage the values returned by these calls. In particular, you will
+generally want the port number to reflect that specified in the original
+request, not the one on which the <strong>Connector</strong> itself is
+listening. You can use the <code>proxyName</code> and <code>proxyPort</code>
+attributes on the <code><Connector></code> element to configure
+these values.</p>
+
+<p>Proxy support can take many forms. The following sections describe
+proxy configurations for several common cases.</p>
+
+</section>
+
+<section name="Apache 1.3 Proxy Support">
+
+<p>Apache 1.3 supports an optional module (<code>mod_proxy</code>) that
+configures the web server to act as a proxy server. This can be used to
+forward requests for a particular web application to a Tomcat 4 instance,
+without having to configure a web connector such as <code>mod_webapp</code>.
+To accomplish this, you need to perform the following tasks:</p>
+<ol>
+<li>Configure your copy of Apache so that it includes the
+ <code>mod_proxy</code> module. If you are building from source,
+ the easiest way to do this is to include the
+ <code>--enable-module=proxy</code> directive on the
+ <code>./configure</code> command line.</li>
+<li>If not already added for you, make sure that you are loading the
+ <code>mod_proxy</code> module at Apache startup time, by using the
+ following directives in your <code>httpd.conf</code> file:
+<source>
+LoadModule proxy_module {path-to-modules}/mod_proxy.so
+AddModule mod_proxy.c
+</source></li>
+<li>Include two directives in your <code>httpd.conf</code> file for
+ each web application that you wish to forward to Tomcat 4. For
+ example, to forward an application at context path <code>/myapp</code>:
+<source>
+ProxyPass /myapp http://localhost:8081/myapp
+ProxyPassReverse /myapp http://localhost:8081/myapp
+</source>
+ which tells Apache to forward URLs of the form
+ <code>http://localhost/myapp/*</code> to the Tomcat 4 connector
+ listening on port 8081.</li>
+<li>Configure your copy of Tomcat 4 to include a special
+ <code><Connector></code> element, with appropriate
+ proxy settings, for example:
+<source>
+<Connector className="org.apache.catalina.connector.http.HttpConnector"
+ port="8081" ...
+ proxyName="www.mycompany.com"
+ proxyPort="80"/>
+</source>
+ which will cause servlets inside this web application to think that
+ all proxied requests were directed to <code>www.mycompany.com</code>
+ on port 80.</li>
+<li>It is legal to omit the <code>proxyName</code> attribute from the
+ <code><Connector></code> element. If you do so, the value
+ returned by <code>request.getServerName()</code> will by the host
+ name on which Tomcat is running. In the example above, it would be
+ <code>localhost</code>.</li>
+<li>If you also have a <code><Connector></code> listening on port
+ 8080 (nested within the same <a href="config/service.html">Service</a>
+ element), the requests to either port will share the same set of
+ virtual hosts and web applications.</li>
+<li>You might wish to use the IP filtering features of your operating
+ system to restrict connections to port 8081 (in this example) to
+ be allowed <strong>only</strong> from the server that is running
+ Apache.</li>
+<li>Alternatively, you can set up a series of web applications that are
+ only available via proxying, as follows:
+ <ul>
+ <li>Configure another <code><Service></code> that contains
+ only a <code><Connector></code> for the proxy port.</li>
+ <li>Configure appropriate <a href="config/engine.html">Engine</a>,
+ <a href="host.html">Host</a>, and
+ <a href="context.html">Context</a> elements for the virtual hosts
+ and web applications accessible via proxying.</li>
+ <li>Optionally, protect port 8081 with IP filters as described
+ earlier.</li>
+ </ul></li>
+<li>When requests are proxied by Apache, the web server will be recording
+ these requests in its access log. Therefore, you will generally want to
+ disable any access logging performed by Tomcat itself.</li>
+</ol>
+
+<p>When requests are proxied in this manner, <strong>all</strong> requests
+for the configured web applications will be processed by Tomcat (including
+requests for static content). You will often be able to improve performance
+by using the <code>mod_webapp</code> web connector instead, which
+automatically configures itself to have Apache handle static content that is
+not processed by filters or security constraints defined within the web
+application's deployment descriptor (<code>/WEB-INF/web.xml</code>).</p>
+
+</section>
+
+</body>
+
+</document>
1.2.2.1 +792 -792 jakarta-tomcat-4.0/webapps/tomcat-docs/realm-howto.xml
Index: realm-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/realm-howto.xml,v
retrieving revision 1.2
retrieving revision 1.2.2.1
diff -u -r1.2 -r1.2.2.1
--- realm-howto.xml 6 Sep 2001 23:06:43 -0000 1.2
+++ realm-howto.xml 26 Mar 2002 14:18:44 -0000 1.2.2.1
@@ -1,792 +1,792 @@
-<?xml version="1.0"?>
-<!DOCTYPE document [
- <!ENTITY project SYSTEM "project.xml">
-]>
-<document>
-
- &project;
-
- <properties>
- <author email="craigmcc@apache.org">Craig R. McClanahan</author>
- <title>Realm Configuration HOW-TO</title>
- </properties>
-
-<body>
-
-
-<section name="Quick Start">
-
-<p>This document describes how to configure Tomcat to support <em>container
-managed security</em>, by connecting to an existing "database" of usernames,
-passwords, and user roles. You only need to care about this if you are using
-a web application that includes one or more
-<code><security-constraint></code> elements, and a
-<code><login-config></code> element defining how users are required
-to authenticate themselves. If you are not utilizing these features, you can
-safely skip this document.</p>
-
-<p>For fundamental background information about container managed security,
-see the <a href="http://java.sun.com/products/servlet/download.html">Servlet
-Specification (Version 2.3)</a>, Section 12. For a more introductory level
-document for web application developers as well as administrators, see
-(<strong>FIXME</strong> - link to backgrounder on container managed security
-to be provided).</p>
-
-<p>For information about utilizing the <em>Single Sign On</em> feature of
-Tomcat 4 (allowing a user to authenticate themselves once across the entire
-set of web applications associated with a virtual host), see
-<a href="config/host.html#Single Sign On">here</a>.</p>
-
-</section>
-
-
-<section name="Overview">
-
-
-<subsection name="What is a Realm?">
-
-<p>A <strong>Realm</strong> is a "database" of usernames and passwords that
-identify valid users of a web application (or set of web applications), plus
-an enumeration of the list of <em>roles</em> associated with each valid user.
-You can think of roles as similar to <em>groups</em> in Unix-like operating
-systems, because access to specific web application resources is granted to
-all users possessing a particular role (rather than enumerating the list of
-associated usernames). A particular user can have any number of roles
-associated with their username.</p>
-
-<p>Although the Servlet Specification describes a portable mechanism for
-applications to <em>declare</em> their security requirements (in the
-<code>web.xml</code> deployment descriptor), there is no portable API
-defining the interface between a servlet container and the associated user
-and role information. In many cases, however, it is desireable to "connect"
-a servlet container to some existing authentication database or mechanism
-that already exists in the production environment. Therefore, Tomcat 4
-defines a Java interface (<code>org.apache.catalina.Realm</code>) that
-can be implemented by "plug in" components to establish this connection.
-Three standard plug-ins are provided, supporting connection to three different
-sources of authentication information:</p>
-<ul>
-<li><a href="#JDBCRealm">JDBCRealm</a> - Accesses authentication information
- stored in a relational database, accessed via a JDBC driver.</li>
-<li><a href="#JNDIRealm">JNDIRealm</a> - Accesses authentication information
- stored in an LDAP based directory server, accessed via a JNDI provider.
- </li>
-<li><a href="#MemoryRealm">MemoryRealm</a> - Accesses authentication
- information stored in an in-memory object collection, which is initialized
- from an XML document (<code>conf/tomcat-users.xml</code>).</li>
-</ul>
-
-<p>It is also possible to write your own <code>Realm</code> implementation,
-and integrate it with Tomcat 4. However, doing this is beyond the scope of
-this document. See (<strong>FIXME</strong> - reference to developer stuff)
-for more information.</p>
-
-</subsection>
-
-
-<subsection name="Configuring a Realm">
-
-<p>Before getting into the details of the standard Realm implementations, it is
-important to understand, in general terms, how a Realm is configured. In
-general, you will be adding an XML element to your <code>conf/server.xml</code>
-configuration file, that looks something like this:</p>
-
-<source>
-<Realm className="... class name for this implementation"
- ... other attributes for this implementation .../>
-</source>
-
-<p>The <code><Realm></code> element can be nested inside one of three
-different elements, which has a direct impact on the "scope" of that Realm
-(i.e. which web applications will share the same authentication information):
-</p>
-<ul>
-<li><em>Inside an <Engine> element</em> - This Realm will be shared
- across ALL web applications on ALL virtual hosts, UNLESS it is overridden
- by a Realm element nested inside a subordinate <code><Host></code>
- or <code><Context></code> element.</li>
-<li><em>Inside a <Host> element</em> - This Realm will be shared across
- ALL web applications for THIS virtual host, UNLESS it is overridden
- by a Realm element nested inside a subordinate <code><Context></code>
- element.</li>
-<li><em>Inside a <Context> element</em> - This Realm will be used ONLY
- for THIS web application.</li>
-</ul>
-
-
-</subsection>
-
-
-</section>
-
-
-<section name="Standard Realm Implementations">
-
-
-<subsection name="JDBCRealm">
-
-<h3>Introduction</h3>
-
-<p><strong>JDBCRealm</strong> is an implementation of the Tomcat 4
-<code>Realm</code> interface that looks up users in a relational database
-accessed via a JDBC driver. There is substantial configuration flexibility
-that lets you adapt to existing table and column names, as long as your
-database structure conforms to the following requirements:</p>
-<ul>
-<li>There must be a table, referenced below as the <em>users</em> table,
- that contains one row for every valid user that this <code>Realm</code>
- should recognize.</li>
-<li>The <em>users</em> table must contain at least two columns (it may
- contain more if your existing applications required it):
- <ul>
- <li>Username to be recognized by Tomcat when the user logs in.</li>
- <li>Password to be recognized by Tomcat when the user logs in.
- This value may in cleartext or digested - see below for more
- information.</li>
- </ul></li>
-<li>There must be a table, referenced below as the <em>user roles</em> table,
- that contains one row for every valid role that is assigned to a
- particular user. It is legal for a user to have zero, one, or more than
- one valid role.</li>
-<li>The <em>user roles</em> table must contain at least two columns (it may
- contain more if your existing applications required it):
- <ul>
- <li>Username to be recognized by Tomcat (same value as is specified
- in the <em>users</em> table).</li>
- <li>Role name of a valid role associated with this user.</li>
- </ul></li>
-</ul>
-
-<h3>Quick Start</h3>
-
-<p>To set up Tomcat to use JDBCRealm, you will need to follow these steps:</p>
-<ol>
-<li>If you have not yet done so, create tables and columns in your database
- that conform to the requirements described above.</li>
-<li>Configure a database username and password for use by Tomcat, that has
- at least read only access to the tables described above. (Tomcat will
- never attempt to write to these tables.)</li>
-<li>Place a copy of the JDBC driver you will be using inside the
- <code>$CATALINA_HOME/server/lib</code> directory (if you do not need it
- visible to web applications) or <code>$CATALINA_HOME/common/lib</code>
- (if it will be used both by Tomcat 4 <em>and</em> by your apps).
- Note that <strong>only</strong> JAR files are recognized!</li>
-<li>Set up a <code><Realm></code> element, as described below, in your
- <code>$CATALINA_HOME/conf/server.xml</code> file.</li>
-<li>Restart Tomcat 4 if it is already running.</li>
-</ol>
-
-<h3>Realm Element Attributes</h3>
-
-<p>To configure JDBCRealm, you will create a <code><Realm></code>
-element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
-as described <a href="#Configuring a Realm">above</a>. The following
-attributes are supported by this implementation:</p>
-
-<attributes>
-
- <attribute name="className" required="true">
- <p>The fully qualified Java class name of this Realm implementation.
- You <strong>MUST</strong> specify the value
- "<code>org.apache.catalina.realm.JDBCRealm</code>" here.</p>
- </attribute>
-
- <attribute name="connectionName" required="true">
- <p>The database username used to establish a JDBC connection.</p>
- </attribute>
-
- <attribute name="connectionPassword" required="true">
- <p>The database password used to establish a JDBC connection.</p>
- </attribute>
-
- <attribute name="connectionURL" required="true">
- <p>The database URL used to establish a JDBC connection.</p>
- </attribute>
-
- <attribute name="debug" required="false">
- <p>The level of debugging detail logged by this Realm
- to the associated <a href="config/logger.html">Logger</a>. Higher numbers
- generate more detailed output. If not specified, the default
- debugging detail level is zero (0).</p>
- </attribute>
-
- <attribute name="digest" required="false">
- <p>The digest algorithm used to store passwords in non-plaintext formats.
- Valid values are those accepted for the algorithm name by the
- <code>java.security.MessageDigest</code> class. See
- <a href="#Digested Passwords">Digested Passwords</a> for more
- information. If not specified, passwords are stored in clear text.</p>
- </attribute>
-
- <attribute name="driverName" required="true">
- <p>The fully qualified Java class name of the JDBC driver to be used.
- Consult the documentation for your JDBC driver for the appropriate
- value.</p>
- </attribute>
-
- <attribute name="roleNameCol" required="true">
- <p>The name of the column, in the <em>user roles</em> table, that
- contains the name of a role assigned to this user.</p>
- </attribute>
-
- <attribute name="userCredCol" required="true">
- <p>The name of the column, in the <em>users</em> table, that contains
- the password for this user (either in clear text, or digested if the
- <code>digest</code> attribute is set).</p>
- </attribute>
-
- <attribute name="userNameCol" required="true">
- <p>The name of the column, in the <em>users</em> and <em>user roles</em>
- tables, that contains the username of this user.</p>
- </attribute>
-
- <attribute name="userRoleTable" required="true">
- <p>The name of the table that contains one row for each <em>role</em>
- assigned to a particular <em>username</em>. This table must include at
- least the columns named by the <code>userNameCol</code> and
- <code>roleNameCol</code> attributes.</p>
- </attribute>
-
- <attribute name="userTable" required="true">
- <p>The name of the table that contains one row for each <em>username</em>
- to be recognized by Tomcat. This table must include at least the columns
- named by the <code>userNameCol</code> and <code>userCredCol</code>
- attributes.</p>
- </attribute>
-
-</attributes>
-
-<h3>Example</h3>
-
-<p>An example SQL script to create the needed tables might look something
-like this (adapt the syntax as required for your particular database):</p>
-<source>
-create table users (
- user_name varchar(15) not null primary key,
- user_pass varchar(15) not null
-);
-
-create table user_roles (
- user_name varchar(15) not null,
- role_name varchar(15) not null,
- primary key (user_name, role_name)
-);
-</source>
-
-<p>Example <code>Realm</code> elements are included (commented out) in the
-default <code>$CATALINA_HOME/conf/server.xml</code> file. Here's an example
-for using a MySQL database called "authority", configured with the tables
-described above, and accessed with username "dbuser" and password "dbpass":</p>
-<source>
-<Realm className="org.apache.catalina.realm.JDBCRealm" debug="99"
- driverName="org.gjt.mm.mysql.Driver"
- connectionURL="jdbc:mysql://localhost/authority?user=dbuser;password=dbpass"
- userTable="users" userNameCol="user_name" userCredCol="user_pass"
- userRoleTable="user_roles" roleNameCol="role_name"/>
-</source>
-
-<h3>Additional Notes</h3>
-
-<p>JDBCRealm operates according to the following rules:</p>
-<ul>
-<li>When a user attempts to access a protected resource for the first time,
- Tomcat 4 will call the <code>authenticate()</code> method of this
- <code>Realm</code>. Thus, any changes you have made to the database
- directly (new users, changed passwords or roles, etc.) will be immediately
- reflected.</li>
-<li>Once a user has been authenticated, the user (and his or her associated
- roles) are cached within Tomcat for the duration of the user's login.
- (For FORM-based authentication, that means until the session times out or
- is invalidated; for BASIC authentication, that means until the user
- closes their browser). Any changes to the database information for an
- already authenticated user will <strong>not</strong> be reflected until
- the next time that user logs on again.</li>
-<li>Administering the information in the <em>users</em> and <em>user roles</em>
- table is the responsibility of your own applications. Tomcat does not
- provide any built-in capabilities to maintain users and roles.</li>
-<li>Debugging and exception messages logged by this <code>Realm</code> will
- be recorded by the <code>Logger</code> that is associated with our
- surrounding <code>Context</code>, <code>Host</code>, or
- <code>Engine</code>. By default, the corresponding Logger will create a
- log file in the <code>$CATALINA_HOME/logs</code> directory.</li>
-</ul>
-
-</subsection>
-
-
-<subsection name="JNDIRealm">
-
-<h3>Introduction</h3>
-
-<p><strong>JNDIRealm</strong> is an implementation of the Tomcat 4
-<code>Realm</code> interface that looks up users in a directory server
-accessed by a JNDI provider (typically, the standard LDAP provider that
-is available with the JNDI API classes). There is substantial configuration
-flexibility that lets you adapt to the existing schema inside your directory
-server, as long as it conforms to the following requirements:</p>
-<ul>
-<li>Each user that can be authenticated is represented by an individual
- element in the top level <code>DirContext</code> that is accessed
- via the <code>connectionURL</code> attribute.</li>
-<li>The <em>user</em> element must have the following characteristics:
- <ul>
- <li>The distinguished name (<code>dn</code>) attribute of this element
- contains the username that is presented for authentication.</li>
- <li>There must be an attribute (identified by the <code>userPassword</code>
- attribute of our <code>Realm</code> element) that contains the user's
- password, either in clear text or digested (see below for more info).
- </li>
- </ul></li>
-<li>Each group of users that has been assigned a particular role is
- represented by an individual element in the top level
- <code>DirContext</code> that is accessed via the
- <code>connectionURL</code> attribute.</li>
-<li>The <em>user group</em> element must have the following characteristics:
- <ul>
- <li>The set of all possible groups of interest can be selected by an LDAP
- search pattern configured by the <code>roleSearch</code> attribute
- of our <code>Realm</code> element.</li>
- <li>The <code>roleSearch</code> pattern optionally includes pattern
- replacements "{0}" for the distinguished name, and/or "{1} for the
- username, of the authenticated user for which roles will be
- retrieved.</li>
- <li>The <code>roleBase</code> attribute can be set to the element that
- is the base of the search for matching roles. If not specified,
- the entire directory context will be searched.</li>
- <li>The <code>roleSubtree</code> attribute can be set to <code>true</code>
- if you wish to search the entire subtree of the directory context.
- The default value of <code>false</code> requests a search of only the
- current level.</li>
- <li>The element includes an attribute (whose name is configured by the
- <code>roleName</code> attribute of our <code>Realm</code> element)
- containing the name of the role represented by this element.</li>
- </ul></li>
-<li>There must be an administrator username and password that Tomcat can
- use to establish a connection to the directory server, with at least
- read-only access to the information described above. A future
- version of Tomcat will support an option to use the user's username and
- password to attempt this connection.</li>
-</ul>
-
-<h3>Quick Start</h3>
-
-<p>To set up Tomcat to use JNDIRealm, you will need to follow these steps:</p>
-<ol>
-<li>Make sure your directory server is configured with a schema that matches
- the requirements listed above.</li>
-<li>Configure a username and password for use by Tomcat, that has
- at least read only access to the information described above. (Tomcat will
- never attempt to modify this information.)</li>
-<li>Place a copy of the JNDI driver you will be using (typically
- <code>ldap.jar</code> available with JNDI) inside the
- <code>$CATALINA_HOME/server/lib</code> directory (if you do not need it
- visible to web applications) or <code>$CATALINA_HOME/common/lib</code>
- (if it will be used both by Tomcat 4 <em>and</em> by your apps).</li>
-<li>Set up a <code><Realm></code> element, as described below, in your
- <code>$CATALINA_HOME/conf/server.xml</code> file.</li>
-<li>Restart Tomcat 4 if it is already running.</li>
-</ol>
-
-<h3>Realm Element Attributes</h3>
-
-<p>To configure JNDIRealm, you will create a <code><Realm></code>
-element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
-as described <a href="#Configuring a Realm">above</a>. The following
-attributes are supported by this implementation:</p>
-
-<attributes>
-
- <attribute name="className" required="true">
- <p>The fully qualified Java class name of this Realm implementation.
- You <strong>MUST</strong> specify the value
- "<code>org.apache.catalina.realm.JDBCRealm</code>" here.</p>
- </attribute>
-
- <attribute name="connectionName" required="true">
- <p>The directory server username used to establish a JNDI connection.</p>
- </attribute>
-
- <attribute name="connectionPassword" required="true">
- <p>The directory server password used to establish a JNDI connection.</p>
- </attribute>
-
- <attribute name="connectionURL" required="true">
- <p>The directory server URL used to establish a JNDI connection.</p>
- </attribute>
-
- <attribute name="contextFactory" required="false">
- <p>The fully qualified Java class name of the JNDI context factory to be
- used for this connection. By default, the standard JNDI LDAP provider
- is used (<code>com.sun.jndi.ldap.LdapCtxFactory</code>).</p>
- </attribute>
-
- <attribute name="debug" required="false">
- <p>The level of debugging detail logged by this Realm
- to the associated <a href="config/logger.html">Logger</a>. Higher numbers
- generate more detailed output. If not specified, the default
- debugging detail level is zero (0).</p>
- </attribute>
-
- <attribute name="digest" required="false">
- <p>The digest algorithm used to store passwords in non-plaintext formats.
- Valid values are those accepted for the algorithm name by the
- <code>java.security.MessageDigest</code> class. See
- <a href="#Digested Passwords">Digested Passwords</a> for more
- information. If not specified, passwords are stored in clear text.</p>
- </attribute>
-
- <attribute name="roleBase" required="false">
- <p>The base element for role searches. If not specified, the top level
- element in the directory context will be used.</p>
- </attribute>
-
- <attribute name="roleName" required="true">
- <p>The name of the directory server attribute containing the role name.</p>
- </attribute>
-
- <attribute name="roleSearch" required="true">
- <p>An LDAP search pattern for selecting roles in this Realm, following the
- syntax supported by the <code>java.text.MessageFormat</code> class. Use
- <code>{0}</code> to substitute in the distinguished name of the user you
- want roles for, and/or <code>{1}</code> to substitute in the username of
- the user you want roles for.</p>
- </attribute>
-
- <attribute name="roleSubtree" required="false">
- <p>Set to <code>true</code> if you want role searches to search subtrees
- of the element selected by <code>roleBase</code>. The default value of
- <code>false</code> causes only the top level element to be searched.</p>
- </attribute>
-
- <attribute name="userPassword" required="true">
- <p>The name of the directory server attribute (in the user element) that
- contains the cleartext or digested user password (depending on the setting
- of the <code>digest</code> attribute).</p>
- </attribute>
-
- <attribute name="userPattern" required="true">
- <p>An LDAP search pattern for selecting users in this Realm, following the
- syntax supported by the <code>java.text.MessageFormat</code> class. Use
- <code>{0}</code> to substitute in the distinguished name of the user you
- want to select.</p>
- </attribute>
-
-</attributes>
-
-<h3>Example</h3>
-
-<p>Creation of the appropriate schema in your directory server is beyond the
-scope of this document, because it is unique to each directory server
-implementation. In the examples below, we will assume that you are using a
-distribution of the OpenLDAP directory server (version 2.0.11 or later), which
-can be downloaded from
-<a href="http://www.openldap.org">http://www.openldap.org</a>. Assume that
-your <code>slapd.conf</code> file contains the following settings
-(among others):</p>
-<source>
-database ldbm
-suffix dc="mycompany",dc="com"
-rootdn "cn=Manager,dc=mycompany,dc=com"
-rootpw secret
-</source>
-
-<p>These settings help us identify values for the values to be specified for
-<code>connectionName</code>, and <code>connectionPassword</code>, and we
-will assume for <code>connectionURL</code> that the directory server runs on
-the same machine as Tomcat. See
-<a href="http://java.sun.com/products/jndi/docs.html">http://java.sun.com/products/jndi/docs.html</a>
-for more information about configuring and using the JNDI LDAP provider.</p>
-
-<p>Next, assume that this directory server has been populated with elements
-as shown below (in LDIF format), which define the same users and roles
-as the default <code>$CATALINA_HOME/conf/tomcat-users.xml</code> does for
-MemoryRealm:</p>
-<source>
-# Define a user named 'tomcat'
-dn: cn=tomcat,dc=mycompany,dc=com
-cn: tomcat
-userPassword: tomcat
-sn: Tomcat User
-objectClass: person
-
-# Define a user named 'role1'
-dn: cn=role1,dc=mycompany,dc=com
-cn: role1
-userPassword: tomcat
-sn: Role1 User
-objectClass: person
-
-# Define a user named 'both'
-dn: cn=both,dc=mycompany,dc=com
-cn: both
-userPassword: tomcat
-sn: Both User
-objectClass: person
-
-# Define an entry to base role searches on
-dn: dc=roles,dc=mycompany,dc=com
-cn: roles
-objectClass: person
-sn: Roles Entry
-
-# Define all members of the 'tomcat' role
-dn: cn=tomcat,dc=roles,dc=mycompany,dc=com
-cn: tomcat
-objectClass: groupOfUniqueNames
-uniqueMember: cn=tomcat,dc=mycompany,dc=com
-uniqueMember: cn=both,dc=mycompany,dc=com
-
-# Define all members of the 'role1' role
-dn: cn=role1,dc=roles,dc=mycompany,dc=com
-cn: role1
-objectClass: groupOfUniqueNames
-uniqueMember: cn=role1,dc=mycompany,dc=com
-uniqueMember: cn=both,dc=mycompany,dc=com
-</source>
-
-<p>An example <code>Realm</code> element for the OpenLDAP directory server
-configured as described above might look like this:</p>
-<source>
-<Realm className="org.apache.catalina.realm.JNDIRealm" debug="99"
- connectionName="cn=Manager,dc=mycompany,dc=com"
-connectionPassword="secret"
- connectionURL="ldap://localhost:389"
- roleBase="dc=roles,dc=mcclan,dc=net"
- roleName="cn"
- roleSearch="(uniqueMember={0})"
- roleSubtree="false"
- userPassword="userPassword"
- userPattern="cn={0},dc=mycompany,dc=com"
-/>
-</source>
-
-<h3>Additional Notes</h3>
-
-<p>JNDIRealm operates according to the following rules:</p>
-<ul>
-<li>When a user attempts to access a protected resource for the first time,
- Tomcat 4 will call the <code>authenticate()</code> method of this
- <code>Realm</code>. Thus, any changes you have made to the database
- directly (new users, changed passwords or roles, etc.) will be immediately
- reflected.</li>
-<li>Once a user has been authenticated, the user (and his or her associated
- roles) are cached within Tomcat for the duration of the user's login.
- (For FORM-based authentication, that means until the session times out or
- is invalidated; for BASIC authentication, that means until the user
- closes their browser). Any changes to the database information for an
- already authenticated user will <strong>not</strong> be reflected until
- the next time that user logs on again.</li>
-<li>Administering the information in the directory server
- is the responsibility of your own applications. Tomcat does not
- provide any built-in capabilities to maintain users and roles.</li>
-<li>Debugging and exception messages logged by this <code>Realm</code> will
- be recorded by the <code>Logger</code> that is associated with our
- surrounding <code>Context</code>, <code>Host</code>, or
- <code>Engine</code>. By default, the corresponding Logger will create a
- log file in the <code>$CATALINA_HOME/logs</code> directory.</li>
-</ul>
-
-</subsection>
-
-
-<subsection name="MemoryRealm">
-
-<h3>Introduction</h3>
-
-<p><strong>MemoryRealm</strong> is a simple demonstration implementation of the
-Tomcat 4 <code>Realm</code> interface. It is not designed for production use.
-At startup time, MemoryRealm loads information about all users, and their
-corresponding roles, from an XML document (by default, this document is loaded from <code>$CATALINA_HOME/conf/tomcat-users.xml</code>). Changes to the data
-in this file are not recognized until Tomcat is restarted.</p>
-
-<h3>Realm Element Attributes</h3>
-
-<p>To configure MemoryRealm, you will create a <code><Realm></code>
-element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
-as described <a href="#Configuring a Realm">above</a>. The following
-attributes are supported by this implementation:</p>
-
-<attributes>
-
- <attribute name="className" required="true">
- <p>The fully qualified Java class name of this Realm implementation.
- You <strong>MUST</strong> specify the value
- "<code>org.apache.catalina.realm.MemoryRealm</code>" here.</p>
- </attribute>
-
- <attribute name="debug" required="false">
- <p>The level of debugging detail logged by this Realm
- to the associated <a href="config/logger.html">Logger</a>. Higher numbers
- generate more detailed output. If not specified, the default
- debugging detail level is zero (0).</p>
- </attribute>
-
- <attribute name="digest" required="false">
- <p>The digest algorithm used to store passwords in non-plaintext formats.
- Valid values are those accepted for the algorithm name by the
- <code>java.security.MessageDigest</code> class. See
- <a href="#Digested Passwords">Digested Passwords</a> for more
- information. If not specified, passwords are stored in clear text.</p>
- </attribute>
-
- <attribute name="pathname" required="false">
- <p>Absolute or relative (to $CATALINA_HOME) pathname of the XML document
- containing our valid usernames, passwords, and roles. See below for more
- information on the format of this file. If not specified, the value
- <code>conf/tomcat-users.xml</code> is used.</p>
- </attribute>
-
-</attributes>
-
-<h3>User File Format</h3>
-
-<p>The users file (by default, <code>conf/tomcat-users.xml</code> must be an
-XML document, with a root element <code><tomcat-users></code>. Nested
-inside the root element will be a <code><user></code> element for each
-valid user, consisting of the following attributes:</p>
-<ul>
-<li><strong>name</strong> - Username this user must log on with.</li>
-<li><strong>password</strong> - Password this user must log on with (in
- clear text if the <code>digest</code> attribute was not set on the
- <code><Realm></code> element, or digested appropriately as
- described <a href="#Digested Passwords">here</a> otherwise).</li>
-<li><strong>roles</strong> - Comma-delimited list of the role names
- associated with this user.</li>
-</ul>
-
-<h3>Example</h3>
-
-<p>The default installation of Tomcat 4 is configured with a MemoryRealm
-nested inside the <code><Engine></code> element, so that it applies
-to all virtual hosts and web applications. The default contents of the
-<code>conf/tomcat-users.xml</code> file is:</p>
-<source>
-<tomcat-users>
- <user name="tomcat" password="tomcat" roles="tomcat" />
- <user name="role1" password="tomcat" roles="role1" />
- <user name="both" password="tomcat" roles="tomcat,role1" />
-</tomcat-users>
-</source>
-
-<h3>Additional Notes</h3>
-
-<p>MemoryRealm operates according to the following rules:</p>
-<ul>
-<li>When Tomcat first starts up, it loads all defined users and their
- associated information from the users file. Changes to the data in
- this file will <strong>not</strong> be recognized until Tomcat is
- restarted.</li>
-<li>When a user attempts to access a protected resource for the first time,
- Tomcat 4 will call the <code>authenticate()</code> method of this
- <code>Realm</code>.</li>
-<li>Once a user has been authenticated, the user (and his or her associated
- roles) are cached within Tomcat for the duration of the user's login.
- (For FORM-based authentication, that means until the session times out or
- is invalidated; for BASIC authentication, that means until the user
- closes their browser).</li>
-<li>Administering the information in the users file is the responsibility
- of your application. Tomcat does not
- provide any built-in capabilities to maintain users and roles.</li>
-<li>Debugging and exception messages logged by this <code>Realm</code> will
- be recorded by the <code>Logger</code> that is associated with our
- surrounding <code>Context</code>, <code>Host</code>, or
- <code>Engine</code>. By default, the corresponding Logger will create a
- log file in the <code>$CATALINA_HOME/logs</code> directory.</li>
-</ul>
-
-
-</subsection>
-
-
-</section>
-
-
-<section name="Common Features">
-
-
-<subsection name="Digested Passwords">
-
-<p>For each of the standard <code>Realm</code> implementations, the user's
-password (by default) is stored in clear text. In many environments, this is
-undesireable because casual observers of the authentication data can collect
-enough information to log on successfully, and impersonate other users.
-To avoid this problem, the standard implementations support the concept of
-<em>digesting</em> user passwords. This causes the stored version of the
-passwords to be encoded (in a form that is not easily reversible), but that
-the <code>Realm</code> implementation can still utilize for authentication.</p>
-
-<p>Digested passwords are selected by specifying the <code>digest</code>
-attribute on your <code><Realm></code> element. The value for this
-attribute must be one of the digest algorithms supported by the
-<code>java.security.MessageDigest</code> class (SHA, MD2, or MD5). When you
-select this option, the contents of the password that is stored in the
-<code>Realm</code> must be the cleartext version of the password, as digested
-by the specified algorithm.</p>
-
-<p>When the <code>authenticate()</code> method of the Realm is called, the
-(cleartext) password specified by the user is itself digested by the same
-algorithm, and the result is compared with the value returned by the
-<code>Realm</code>. An equal match implies that the cleartext version of the
-original password is the same as the one presented by the user, so that this
-user should be authorized.</p>
-
-<p>To calculate the digested value of a cleartext password, two convenience
-techniques are supported:</p>
-<ul>
-<li>If you are writing an application that needs to calculate digested
- passowrds dynamically, call the static <code>Digest()</code> method of the
- <code>org.apache.catalina.realm.RealmBase</code> class, passing the
- cleartext password and the digest algorithm name as arguments. This
- method will return the digested password.</li>
-<li>If you want to execute a command line utility to calculate the digested
- password, simply execute
-<source>
-java org.apache.catalina.realm.RealmBase \
- -a {algorithm} {cleartext-password}
-</source>
- and the digested version of this cleartext password will be returned to
- standard output.</li>
-</ul>
-
-<p>To use either of the above techniques, the
-<code>$CATALINA_HOME/server/lib/catalina.jar</code> file will need to be
-on your class path to make the <code>RealmBase</code> class available.</p>
-
-</subsection>
-
-
-<subsection name="Example Application">
-
-<p>The example application shipped with Tomcat 4 includes an area that is
-protected by a security constraint, utilizing form-based login. To access it,
-point your browser at
-<a href="http://localhost:8080/examples/jsp/security/protected/">http://localhost:8080/examples/jsp/security/protected/</a>
-and log on with one of the usernames and passwords described for the default
-<a href="#MemoryRealm">MemoryRealm</a>.</p>
-
-</subsection>
-
-
-<subsection name="Manager Application">
-
-<p>If you wish to use the <a href="manager-howto.html">Manager Application</a>
-to deploy and undeploy applications in a running Tomcat 4 installation, you
-MUST add the "manager" role to at least one username in your selected Realm
-implementation. This is because the manager web application itself uses a
-security constraint that requires role "manager" to access ANY request URI
-within that application.</p>
-
-<p>For security reasons, no username in the default Realm (i.e. using
-<code>conf/tomcat-users.xml</code> is assigned the "manager" role. Therfore,
-no one will be able to utilize the features of this application until the
-Tomcat administrator specifically assigns this role to one or more users.</p>
-
-</subsection>
-
-
-</section>
-
-
-</body>
-
-</document>
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document>
+
+ &project;
+
+ <properties>
+ <author email="craigmcc@apache.org">Craig R. McClanahan</author>
+ <title>Realm Configuration HOW-TO</title>
+ </properties>
+
+<body>
+
+
+<section name="Quick Start">
+
+<p>This document describes how to configure Tomcat to support <em>container
+managed security</em>, by connecting to an existing "database" of usernames,
+passwords, and user roles. You only need to care about this if you are using
+a web application that includes one or more
+<code><security-constraint></code> elements, and a
+<code><login-config></code> element defining how users are required
+to authenticate themselves. If you are not utilizing these features, you can
+safely skip this document.</p>
+
+<p>For fundamental background information about container managed security,
+see the <a href="http://java.sun.com/products/servlet/download.html">Servlet
+Specification (Version 2.3)</a>, Section 12. For a more introductory level
+document for web application developers as well as administrators, see
+(<strong>FIXME</strong> - link to backgrounder on container managed security
+to be provided).</p>
+
+<p>For information about utilizing the <em>Single Sign On</em> feature of
+Tomcat 4 (allowing a user to authenticate themselves once across the entire
+set of web applications associated with a virtual host), see
+<a href="config/host.html#Single Sign On">here</a>.</p>
+
+</section>
+
+
+<section name="Overview">
+
+
+<subsection name="What is a Realm?">
+
+<p>A <strong>Realm</strong> is a "database" of usernames and passwords that
+identify valid users of a web application (or set of web applications), plus
+an enumeration of the list of <em>roles</em> associated with each valid user.
+You can think of roles as similar to <em>groups</em> in Unix-like operating
+systems, because access to specific web application resources is granted to
+all users possessing a particular role (rather than enumerating the list of
+associated usernames). A particular user can have any number of roles
+associated with their username.</p>
+
+<p>Although the Servlet Specification describes a portable mechanism for
+applications to <em>declare</em> their security requirements (in the
+<code>web.xml</code> deployment descriptor), there is no portable API
+defining the interface between a servlet container and the associated user
+and role information. In many cases, however, it is desireable to "connect"
+a servlet container to some existing authentication database or mechanism
+that already exists in the production environment. Therefore, Tomcat 4
+defines a Java interface (<code>org.apache.catalina.Realm</code>) that
+can be implemented by "plug in" components to establish this connection.
+Three standard plug-ins are provided, supporting connection to three different
+sources of authentication information:</p>
+<ul>
+<li><a href="#JDBCRealm">JDBCRealm</a> - Accesses authentication information
+ stored in a relational database, accessed via a JDBC driver.</li>
+<li><a href="#JNDIRealm">JNDIRealm</a> - Accesses authentication information
+ stored in an LDAP based directory server, accessed via a JNDI provider.
+ </li>
+<li><a href="#MemoryRealm">MemoryRealm</a> - Accesses authentication
+ information stored in an in-memory object collection, which is initialized
+ from an XML document (<code>conf/tomcat-users.xml</code>).</li>
+</ul>
+
+<p>It is also possible to write your own <code>Realm</code> implementation,
+and integrate it with Tomcat 4. However, doing this is beyond the scope of
+this document. See (<strong>FIXME</strong> - reference to developer stuff)
+for more information.</p>
+
+</subsection>
+
+
+<subsection name="Configuring a Realm">
+
+<p>Before getting into the details of the standard Realm implementations, it is
+important to understand, in general terms, how a Realm is configured. In
+general, you will be adding an XML element to your <code>conf/server.xml</code>
+configuration file, that looks something like this:</p>
+
+<source>
+<Realm className="... class name for this implementation"
+ ... other attributes for this implementation .../>
+</source>
+
+<p>The <code><Realm></code> element can be nested inside one of three
+different elements, which has a direct impact on the "scope" of that Realm
+(i.e. which web applications will share the same authentication information):
+</p>
+<ul>
+<li><em>Inside an <Engine> element</em> - This Realm will be shared
+ across ALL web applications on ALL virtual hosts, UNLESS it is overridden
+ by a Realm element nested inside a subordinate <code><Host></code>
+ or <code><Context></code> element.</li>
+<li><em>Inside a <Host> element</em> - This Realm will be shared across
+ ALL web applications for THIS virtual host, UNLESS it is overridden
+ by a Realm element nested inside a subordinate <code><Context></code>
+ element.</li>
+<li><em>Inside a <Context> element</em> - This Realm will be used ONLY
+ for THIS web application.</li>
+</ul>
+
+
+</subsection>
+
+
+</section>
+
+
+<section name="Standard Realm Implementations">
+
+
+<subsection name="JDBCRealm">
+
+<h3>Introduction</h3>
+
+<p><strong>JDBCRealm</strong> is an implementation of the Tomcat 4
+<code>Realm</code> interface that looks up users in a relational database
+accessed via a JDBC driver. There is substantial configuration flexibility
+that lets you adapt to existing table and column names, as long as your
+database structure conforms to the following requirements:</p>
+<ul>
+<li>There must be a table, referenced below as the <em>users</em> table,
+ that contains one row for every valid user that this <code>Realm</code>
+ should recognize.</li>
+<li>The <em>users</em> table must contain at least two columns (it may
+ contain more if your existing applications required it):
+ <ul>
+ <li>Username to be recognized by Tomcat when the user logs in.</li>
+ <li>Password to be recognized by Tomcat when the user logs in.
+ This value may in cleartext or digested - see below for more
+ information.</li>
+ </ul></li>
+<li>There must be a table, referenced below as the <em>user roles</em> table,
+ that contains one row for every valid role that is assigned to a
+ particular user. It is legal for a user to have zero, one, or more than
+ one valid role.</li>
+<li>The <em>user roles</em> table must contain at least two columns (it may
+ contain more if your existing applications required it):
+ <ul>
+ <li>Username to be recognized by Tomcat (same value as is specified
+ in the <em>users</em> table).</li>
+ <li>Role name of a valid role associated with this user.</li>
+ </ul></li>
+</ul>
+
+<h3>Quick Start</h3>
+
+<p>To set up Tomcat to use JDBCRealm, you will need to follow these steps:</p>
+<ol>
+<li>If you have not yet done so, create tables and columns in your database
+ that conform to the requirements described above.</li>
+<li>Configure a database username and password for use by Tomcat, that has
+ at least read only access to the tables described above. (Tomcat will
+ never attempt to write to these tables.)</li>
+<li>Place a copy of the JDBC driver you will be using inside the
+ <code>$CATALINA_HOME/server/lib</code> directory (if you do not need it
+ visible to web applications) or <code>$CATALINA_HOME/common/lib</code>
+ (if it will be used both by Tomcat 4 <em>and</em> by your apps).
+ Note that <strong>only</strong> JAR files are recognized!</li>
+<li>Set up a <code><Realm></code> element, as described below, in your
+ <code>$CATALINA_HOME/conf/server.xml</code> file.</li>
+<li>Restart Tomcat 4 if it is already running.</li>
+</ol>
+
+<h3>Realm Element Attributes</h3>
+
+<p>To configure JDBCRealm, you will create a <code><Realm></code>
+element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
+as described <a href="#Configuring a Realm">above</a>. The following
+attributes are supported by this implementation:</p>
+
+<attributes>
+
+ <attribute name="className" required="true">
+ <p>The fully qualified Java class name of this Realm implementation.
+ You <strong>MUST</strong> specify the value
+ "<code>org.apache.catalina.realm.JDBCRealm</code>" here.</p>
+ </attribute>
+
+ <attribute name="connectionName" required="true">
+ <p>The database username used to establish a JDBC connection.</p>
+ </attribute>
+
+ <attribute name="connectionPassword" required="true">
+ <p>The database password used to establish a JDBC connection.</p>
+ </attribute>
+
+ <attribute name="connectionURL" required="true">
+ <p>The database URL used to establish a JDBC connection.</p>
+ </attribute>
+
+ <attribute name="debug" required="false">
+ <p>The level of debugging detail logged by this Realm
+ to the associated <a href="config/logger.html">Logger</a>. Higher numbers
+ generate more detailed output. If not specified, the default
+ debugging detail level is zero (0).</p>
+ </attribute>
+
+ <attribute name="digest" required="false">
+ <p>The digest algorithm used to store passwords in non-plaintext formats.
+ Valid values are those accepted for the algorithm name by the
+ <code>java.security.MessageDigest</code> class. See
+ <a href="#Digested Passwords">Digested Passwords</a> for more
+ information. If not specified, passwords are stored in clear text.</p>
+ </attribute>
+
+ <attribute name="driverName" required="true">
+ <p>The fully qualified Java class name of the JDBC driver to be used.
+ Consult the documentation for your JDBC driver for the appropriate
+ value.</p>
+ </attribute>
+
+ <attribute name="roleNameCol" required="true">
+ <p>The name of the column, in the <em>user roles</em> table, that
+ contains the name of a role assigned to this user.</p>
+ </attribute>
+
+ <attribute name="userCredCol" required="true">
+ <p>The name of the column, in the <em>users</em> table, that contains
+ the password for this user (either in clear text, or digested if the
+ <code>digest</code> attribute is set).</p>
+ </attribute>
+
+ <attribute name="userNameCol" required="true">
+ <p>The name of the column, in the <em>users</em> and <em>user roles</em>
+ tables, that contains the username of this user.</p>
+ </attribute>
+
+ <attribute name="userRoleTable" required="true">
+ <p>The name of the table that contains one row for each <em>role</em>
+ assigned to a particular <em>username</em>. This table must include at
+ least the columns named by the <code>userNameCol</code> and
+ <code>roleNameCol</code> attributes.</p>
+ </attribute>
+
+ <attribute name="userTable" required="true">
+ <p>The name of the table that contains one row for each <em>username</em>
+ to be recognized by Tomcat. This table must include at least the columns
+ named by the <code>userNameCol</code> and <code>userCredCol</code>
+ attributes.</p>
+ </attribute>
+
+</attributes>
+
+<h3>Example</h3>
+
+<p>An example SQL script to create the needed tables might look something
+like this (adapt the syntax as required for your particular database):</p>
+<source>
+create table users (
+ user_name varchar(15) not null primary key,
+ user_pass varchar(15) not null
+);
+
+create table user_roles (
+ user_name varchar(15) not null,
+ role_name varchar(15) not null,
+ primary key (user_name, role_name)
+);
+</source>
+
+<p>Example <code>Realm</code> elements are included (commented out) in the
+default <code>$CATALINA_HOME/conf/server.xml</code> file. Here's an example
+for using a MySQL database called "authority", configured with the tables
+described above, and accessed with username "dbuser" and password "dbpass":</p>
+<source>
+<Realm className="org.apache.catalina.realm.JDBCRealm" debug="99"
+ driverName="org.gjt.mm.mysql.Driver"
+ connectionURL="jdbc:mysql://localhost/authority?user=dbuser;password=dbpass"
+ userTable="users" userNameCol="user_name" userCredCol="user_pass"
+ userRoleTable="user_roles" roleNameCol="role_name"/>
+</source>
+
+<h3>Additional Notes</h3>
+
+<p>JDBCRealm operates according to the following rules:</p>
+<ul>
+<li>When a user attempts to access a protected resource for the first time,
+ Tomcat 4 will call the <code>authenticate()</code> method of this
+ <code>Realm</code>. Thus, any changes you have made to the database
+ directly (new users, changed passwords or roles, etc.) will be immediately
+ reflected.</li>
+<li>Once a user has been authenticated, the user (and his or her associated
+ roles) are cached within Tomcat for the duration of the user's login.
+ (For FORM-based authentication, that means until the session times out or
+ is invalidated; for BASIC authentication, that means until the user
+ closes their browser). Any changes to the database information for an
+ already authenticated user will <strong>not</strong> be reflected until
+ the next time that user logs on again.</li>
+<li>Administering the information in the <em>users</em> and <em>user roles</em>
+ table is the responsibility of your own applications. Tomcat does not
+ provide any built-in capabilities to maintain users and roles.</li>
+<li>Debugging and exception messages logged by this <code>Realm</code> will
+ be recorded by the <code>Logger</code> that is associated with our
+ surrounding <code>Context</code>, <code>Host</code>, or
+ <code>Engine</code>. By default, the corresponding Logger will create a
+ log file in the <code>$CATALINA_HOME/logs</code> directory.</li>
+</ul>
+
+</subsection>
+
+
+<subsection name="JNDIRealm">
+
+<h3>Introduction</h3>
+
+<p><strong>JNDIRealm</strong> is an implementation of the Tomcat 4
+<code>Realm</code> interface that looks up users in a directory server
+accessed by a JNDI provider (typically, the standard LDAP provider that
+is available with the JNDI API classes). There is substantial configuration
+flexibility that lets you adapt to the existing schema inside your directory
+server, as long as it conforms to the following requirements:</p>
+<ul>
+<li>Each user that can be authenticated is represented by an individual
+ element in the top level <code>DirContext</code> that is accessed
+ via the <code>connectionURL</code> attribute.</li>
+<li>The <em>user</em> element must have the following characteristics:
+ <ul>
+ <li>The distinguished name (<code>dn</code>) attribute of this element
+ contains the username that is presented for authentication.</li>
+ <li>There must be an attribute (identified by the <code>userPassword</code>
+ attribute of our <code>Realm</code> element) that contains the user's
+ password, either in clear text or digested (see below for more info).
+ </li>
+ </ul></li>
+<li>Each group of users that has been assigned a particular role is
+ represented by an individual element in the top level
+ <code>DirContext</code> that is accessed via the
+ <code>connectionURL</code> attribute.</li>
+<li>The <em>user group</em> element must have the following characteristics:
+ <ul>
+ <li>The set of all possible groups of interest can be selected by an LDAP
+ search pattern configured by the <code>roleSearch</code> attribute
+ of our <code>Realm</code> element.</li>
+ <li>The <code>roleSearch</code> pattern optionally includes pattern
+ replacements "{0}" for the distinguished name, and/or "{1} for the
+ username, of the authenticated user for which roles will be
+ retrieved.</li>
+ <li>The <code>roleBase</code> attribute can be set to the element that
+ is the base of the search for matching roles. If not specified,
+ the entire directory context will be searched.</li>
+ <li>The <code>roleSubtree</code> attribute can be set to <code>true</code>
+ if you wish to search the entire subtree of the directory context.
+ The default value of <code>false</code> requests a search of only the
+ current level.</li>
+ <li>The element includes an attribute (whose name is configured by the
+ <code>roleName</code> attribute of our <code>Realm</code> element)
+ containing the name of the role represented by this element.</li>
+ </ul></li>
+<li>There must be an administrator username and password that Tomcat can
+ use to establish a connection to the directory server, with at least
+ read-only access to the information described above. A future
+ version of Tomcat will support an option to use the user's username and
+ password to attempt this connection.</li>
+</ul>
+
+<h3>Quick Start</h3>
+
+<p>To set up Tomcat to use JNDIRealm, you will need to follow these steps:</p>
+<ol>
+<li>Make sure your directory server is configured with a schema that matches
+ the requirements listed above.</li>
+<li>Configure a username and password for use by Tomcat, that has
+ at least read only access to the information described above. (Tomcat will
+ never attempt to modify this information.)</li>
+<li>Place a copy of the JNDI driver you will be using (typically
+ <code>ldap.jar</code> available with JNDI) inside the
+ <code>$CATALINA_HOME/server/lib</code> directory (if you do not need it
+ visible to web applications) or <code>$CATALINA_HOME/common/lib</code>
+ (if it will be used both by Tomcat 4 <em>and</em> by your apps).</li>
+<li>Set up a <code><Realm></code> element, as described below, in your
+ <code>$CATALINA_HOME/conf/server.xml</code> file.</li>
+<li>Restart Tomcat 4 if it is already running.</li>
+</ol>
+
+<h3>Realm Element Attributes</h3>
+
+<p>To configure JNDIRealm, you will create a <code><Realm></code>
+element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
+as described <a href="#Configuring a Realm">above</a>. The following
+attributes are supported by this implementation:</p>
+
+<attributes>
+
+ <attribute name="className" required="true">
+ <p>The fully qualified Java class name of this Realm implementation.
+ You <strong>MUST</strong> specify the value
+ "<code>org.apache.catalina.realm.JDBCRealm</code>" here.</p>
+ </attribute>
+
+ <attribute name="connectionName" required="true">
+ <p>The directory server username used to establish a JNDI connection.</p>
+ </attribute>
+
+ <attribute name="connectionPassword" required="true">
+ <p>The directory server password used to establish a JNDI connection.</p>
+ </attribute>
+
+ <attribute name="connectionURL" required="true">
+ <p>The directory server URL used to establish a JNDI connection.</p>
+ </attribute>
+
+ <attribute name="contextFactory" required="false">
+ <p>The fully qualified Java class name of the JNDI context factory to be
+ used for this connection. By default, the standard JNDI LDAP provider
+ is used (<code>com.sun.jndi.ldap.LdapCtxFactory</code>).</p>
+ </attribute>
+
+ <attribute name="debug" required="false">
+ <p>The level of debugging detail logged by this Realm
+ to the associated <a href="config/logger.html">Logger</a>. Higher numbers
+ generate more detailed output. If not specified, the default
+ debugging detail level is zero (0).</p>
+ </attribute>
+
+ <attribute name="digest" required="false">
+ <p>The digest algorithm used to store passwords in non-plaintext formats.
+ Valid values are those accepted for the algorithm name by the
+ <code>java.security.MessageDigest</code> class. See
+ <a href="#Digested Passwords">Digested Passwords</a> for more
+ information. If not specified, passwords are stored in clear text.</p>
+ </attribute>
+
+ <attribute name="roleBase" required="false">
+ <p>The base element for role searches. If not specified, the top level
+ element in the directory context will be used.</p>
+ </attribute>
+
+ <attribute name="roleName" required="true">
+ <p>The name of the directory server attribute containing the role name.</p>
+ </attribute>
+
+ <attribute name="roleSearch" required="true">
+ <p>An LDAP search pattern for selecting roles in this Realm, following the
+ syntax supported by the <code>java.text.MessageFormat</code> class. Use
+ <code>{0}</code> to substitute in the distinguished name of the user you
+ want roles for, and/or <code>{1}</code> to substitute in the username of
+ the user you want roles for.</p>
+ </attribute>
+
+ <attribute name="roleSubtree" required="false">
+ <p>Set to <code>true</code> if you want role searches to search subtrees
+ of the element selected by <code>roleBase</code>. The default value of
+ <code>false</code> causes only the top level element to be searched.</p>
+ </attribute>
+
+ <attribute name="userPassword" required="true">
+ <p>The name of the directory server attribute (in the user element) that
+ contains the cleartext or digested user password (depending on the setting
+ of the <code>digest</code> attribute).</p>
+ </attribute>
+
+ <attribute name="userPattern" required="true">
+ <p>An LDAP search pattern for selecting users in this Realm, following the
+ syntax supported by the <code>java.text.MessageFormat</code> class. Use
+ <code>{0}</code> to substitute in the distinguished name of the user you
+ want to select.</p>
+ </attribute>
+
+</attributes>
+
+<h3>Example</h3>
+
+<p>Creation of the appropriate schema in your directory server is beyond the
+scope of this document, because it is unique to each directory server
+implementation. In the examples below, we will assume that you are using a
+distribution of the OpenLDAP directory server (version 2.0.11 or later), which
+can be downloaded from
+<a href="http://www.openldap.org">http://www.openldap.org</a>. Assume that
+your <code>slapd.conf</code> file contains the following settings
+(among others):</p>
+<source>
+database ldbm
+suffix dc="mycompany",dc="com"
+rootdn "cn=Manager,dc=mycompany,dc=com"
+rootpw secret
+</source>
+
+<p>These settings help us identify values for the values to be specified for
+<code>connectionName</code>, and <code>connectionPassword</code>, and we
+will assume for <code>connectionURL</code> that the directory server runs on
+the same machine as Tomcat. See
+<a href="http://java.sun.com/products/jndi/docs.html">http://java.sun.com/products/jndi/docs.html</a>
+for more information about configuring and using the JNDI LDAP provider.</p>
+
+<p>Next, assume that this directory server has been populated with elements
+as shown below (in LDIF format), which define the same users and roles
+as the default <code>$CATALINA_HOME/conf/tomcat-users.xml</code> does for
+MemoryRealm:</p>
+<source>
+# Define a user named 'tomcat'
+dn: cn=tomcat,dc=mycompany,dc=com
+cn: tomcat
+userPassword: tomcat
+sn: Tomcat User
+objectClass: person
+
+# Define a user named 'role1'
+dn: cn=role1,dc=mycompany,dc=com
+cn: role1
+userPassword: tomcat
+sn: Role1 User
+objectClass: person
+
+# Define a user named 'both'
+dn: cn=both,dc=mycompany,dc=com
+cn: both
+userPassword: tomcat
+sn: Both User
+objectClass: person
+
+# Define an entry to base role searches on
+dn: dc=roles,dc=mycompany,dc=com
+cn: roles
+objectClass: person
+sn: Roles Entry
+
+# Define all members of the 'tomcat' role
+dn: cn=tomcat,dc=roles,dc=mycompany,dc=com
+cn: tomcat
+objectClass: groupOfUniqueNames
+uniqueMember: cn=tomcat,dc=mycompany,dc=com
+uniqueMember: cn=both,dc=mycompany,dc=com
+
+# Define all members of the 'role1' role
+dn: cn=role1,dc=roles,dc=mycompany,dc=com
+cn: role1
+objectClass: groupOfUniqueNames
+uniqueMember: cn=role1,dc=mycompany,dc=com
+uniqueMember: cn=both,dc=mycompany,dc=com
+</source>
+
+<p>An example <code>Realm</code> element for the OpenLDAP directory server
+configured as described above might look like this:</p>
+<source>
+<Realm className="org.apache.catalina.realm.JNDIRealm" debug="99"
+ connectionName="cn=Manager,dc=mycompany,dc=com"
+connectionPassword="secret"
+ connectionURL="ldap://localhost:389"
+ roleBase="dc=roles,dc=mcclan,dc=net"
+ roleName="cn"
+ roleSearch="(uniqueMember={0})"
+ roleSubtree="false"
+ userPassword="userPassword"
+ userPattern="cn={0},dc=mycompany,dc=com"
+/>
+</source>
+
+<h3>Additional Notes</h3>
+
+<p>JNDIRealm operates according to the following rules:</p>
+<ul>
+<li>When a user attempts to access a protected resource for the first time,
+ Tomcat 4 will call the <code>authenticate()</code> method of this
+ <code>Realm</code>. Thus, any changes you have made to the database
+ directly (new users, changed passwords or roles, etc.) will be immediately
+ reflected.</li>
+<li>Once a user has been authenticated, the user (and his or her associated
+ roles) are cached within Tomcat for the duration of the user's login.
+ (For FORM-based authentication, that means until the session times out or
+ is invalidated; for BASIC authentication, that means until the user
+ closes their browser). Any changes to the database information for an
+ already authenticated user will <strong>not</strong> be reflected until
+ the next time that user logs on again.</li>
+<li>Administering the information in the directory server
+ is the responsibility of your own applications. Tomcat does not
+ provide any built-in capabilities to maintain users and roles.</li>
+<li>Debugging and exception messages logged by this <code>Realm</code> will
+ be recorded by the <code>Logger</code> that is associated with our
+ surrounding <code>Context</code>, <code>Host</code>, or
+ <code>Engine</code>. By default, the corresponding Logger will create a
+ log file in the <code>$CATALINA_HOME/logs</code> directory.</li>
+</ul>
+
+</subsection>
+
+
+<subsection name="MemoryRealm">
+
+<h3>Introduction</h3>
+
+<p><strong>MemoryRealm</strong> is a simple demonstration implementation of the
+Tomcat 4 <code>Realm</code> interface. It is not designed for production use.
+At startup time, MemoryRealm loads information about all users, and their
+corresponding roles, from an XML document (by default, this document is loaded from <code>$CATALINA_HOME/conf/tomcat-users.xml</code>). Changes to the data
+in this file are not recognized until Tomcat is restarted.</p>
+
+<h3>Realm Element Attributes</h3>
+
+<p>To configure MemoryRealm, you will create a <code><Realm></code>
+element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
+as described <a href="#Configuring a Realm">above</a>. The following
+attributes are supported by this implementation:</p>
+
+<attributes>
+
+ <attribute name="className" required="true">
+ <p>The fully qualified Java class name of this Realm implementation.
+ You <strong>MUST</strong> specify the value
+ "<code>org.apache.catalina.realm.MemoryRealm</code>" here.</p>
+ </attribute>
+
+ <attribute name="debug" required="false">
+ <p>The level of debugging detail logged by this Realm
+ to the associated <a href="config/logger.html">Logger</a>. Higher numbers
+ generate more detailed output. If not specified, the default
+ debugging detail level is zero (0).</p>
+ </attribute>
+
+ <attribute name="digest" required="false">
+ <p>The digest algorithm used to store passwords in non-plaintext formats.
+ Valid values are those accepted for the algorithm name by the
+ <code>java.security.MessageDigest</code> class. See
+ <a href="#Digested Passwords">Digested Passwords</a> for more
+ information. If not specified, passwords are stored in clear text.</p>
+ </attribute>
+
+ <attribute name="pathname" required="false">
+ <p>Absolute or relative (to $CATALINA_HOME) pathname of the XML document
+ containing our valid usernames, passwords, and roles. See below for more
+ information on the format of this file. If not specified, the value
+ <code>conf/tomcat-users.xml</code> is used.</p>
+ </attribute>
+
+</attributes>
+
+<h3>User File Format</h3>
+
+<p>The users file (by default, <code>conf/tomcat-users.xml</code> must be an
+XML document, with a root element <code><tomcat-users></code>. Nested
+inside the root element will be a <code><user></code> element for each
+valid user, consisting of the following attributes:</p>
+<ul>
+<li><strong>name</strong> - Username this user must log on with.</li>
+<li><strong>password</strong> - Password this user must log on with (in
+ clear text if the <code>digest</code> attribute was not set on the
+ <code><Realm></code> element, or digested appropriately as
+ described <a href="#Digested Passwords">here</a> otherwise).</li>
+<li><strong>roles</strong> - Comma-delimited list of the role names
+ associated with this user.</li>
+</ul>
+
+<h3>Example</h3>
+
+<p>The default installation of Tomcat 4 is configured with a MemoryRealm
+nested inside the <code><Engine></code> element, so that it applies
+to all virtual hosts and web applications. The default contents of the
+<code>conf/tomcat-users.xml</code> file is:</p>
+<source>
+<tomcat-users>
+ <user name="tomcat" password="tomcat" roles="tomcat" />
+ <user name="role1" password="tomcat" roles="role1" />
+ <user name="both" password="tomcat" roles="tomcat,role1" />
+</tomcat-users>
+</source>
+
+<h3>Additional Notes</h3>
+
+<p>MemoryRealm operates according to the following rules:</p>
+<ul>
+<li>When Tomcat first starts up, it loads all defined users and their
+ associated information from the users file. Changes to the data in
+ this file will <strong>not</strong> be recognized until Tomcat is
+ restarted.</li>
+<li>When a user attempts to access a protected resource for the first time,
+ Tomcat 4 will call the <code>authenticate()</code> method of this
+ <code>Realm</code>.</li>
+<li>Once a user has been authenticated, the user (and his or her associated
+ roles) are cached within Tomcat for the duration of the user's login.
+ (For FORM-based authentication, that means until the session times out or
+ is invalidated; for BASIC authentication, that means until the user
+ closes their browser).</li>
+<li>Administering the information in the users file is the responsibility
+ of your application. Tomcat does not
+ provide any built-in capabilities to maintain users and roles.</li>
+<li>Debugging and exception messages logged by this <code>Realm</code> will
+ be recorded by the <code>Logger</code> that is associated with our
+ surrounding <code>Context</code>, <code>Host</code>, or
+ <code>Engine</code>. By default, the corresponding Logger will create a
+ log file in the <code>$CATALINA_HOME/logs</code> directory.</li>
+</ul>
+
+
+</subsection>
+
+
+</section>
+
+
+<section name="Common Features">
+
+
+<subsection name="Digested Passwords">
+
+<p>For each of the standard <code>Realm</code> implementations, the user's
+password (by default) is stored in clear text. In many environments, this is
+undesireable because casual observers of the authentication data can collect
+enough information to log on successfully, and impersonate other users.
+To avoid this problem, the standard implementations support the concept of
+<em>digesting</em> user passwords. This causes the stored version of the
+passwords to be encoded (in a form that is not easily reversible), but that
+the <code>Realm</code> implementation can still utilize for authentication.</p>
+
+<p>Digested passwords are selected by specifying the <code>digest</code>
+attribute on your <code><Realm></code> element. The value for this
+attribute must be one of the digest algorithms supported by the
+<code>java.security.MessageDigest</code> class (SHA, MD2, or MD5). When you
+select this option, the contents of the password that is stored in the
+<code>Realm</code> must be the cleartext version of the password, as digested
+by the specified algorithm.</p>
+
+<p>When the <code>authenticate()</code> method of the Realm is called, the
+(cleartext) password specified by the user is itself digested by the same
+algorithm, and the result is compared with the value returned by the
+<code>Realm</code>. An equal match implies that the cleartext version of the
+original password is the same as the one presented by the user, so that this
+user should be authorized.</p>
+
+<p>To calculate the digested value of a cleartext password, two convenience
+techniques are supported:</p>
+<ul>
+<li>If you are writing an application that needs to calculate digested
+ passowrds dynamically, call the static <code>Digest()</code> method of the
+ <code>org.apache.catalina.realm.RealmBase</code> class, passing the
+ cleartext password and the digest algorithm name as arguments. This
+ method will return the digested password.</li>
+<li>If you want to execute a command line utility to calculate the digested
+ password, simply execute
+<source>
+java org.apache.catalina.realm.RealmBase \
+ -a {algorithm} {cleartext-password}
+</source>
+ and the digested version of this cleartext password will be returned to
+ standard output.</li>
+</ul>
+
+<p>To use either of the above techniques, the
+<code>$CATALINA_HOME/server/lib/catalina.jar</code> file will need to be
+on your class path to make the <code>RealmBase</code> class available.</p>
+
+</subsection>
+
+
+<subsection name="Example Application">
+
+<p>The example application shipped with Tomcat 4 includes an area that is
+protected by a security constraint, utilizing form-based login. To access it,
+point your browser at
+<a href="http://localhost:8080/examples/jsp/security/protected/">http://localhost:8080/examples/jsp/security/protected/</a>
+and log on with one of the usernames and passwords described for the default
+<a href="#MemoryRealm">MemoryRealm</a>.</p>
+
+</subsection>
+
+
+<subsection name="Manager Application">
+
+<p>If you wish to use the <a href="manager-howto.html">Manager Application</a>
+to deploy and undeploy applications in a running Tomcat 4 installation, you
+MUST add the "manager" role to at least one username in your selected Realm
+implementation. This is because the manager web application itself uses a
+security constraint that requires role "manager" to access ANY request URI
+within that application.</p>
+
+<p>For security reasons, no username in the default Realm (i.e. using
+<code>conf/tomcat-users.xml</code> is assigned the "manager" role. Therfore,
+no one will be able to utilize the features of this application until the
+Tomcat administrator specifically assigns this role to one or more users.</p>
+
+</subsection>
+
+
+</section>
+
+
+</body>
+
+</document>
1.7.2.3 +420 -420 jakarta-tomcat-4.0/webapps/tomcat-docs/ssl-howto.xml
Index: ssl-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/ssl-howto.xml,v
retrieving revision 1.7.2.2
retrieving revision 1.7.2.3
diff -u -r1.7.2.2 -r1.7.2.3
--- ssl-howto.xml 25 Sep 2001 04:57:29 -0000 1.7.2.2
+++ ssl-howto.xml 26 Mar 2002 14:18:44 -0000 1.7.2.3
@@ -1,420 +1,420 @@
-<?xml version="1.0"?>
-<!DOCTYPE document [
- <!ENTITY project SYSTEM "project.xml">
-]>
-<document>
-
- &project;
-
- <properties>
- <author email="ccain@apache.org">Christopher Cain</author>
- <title>SSL Configuration HOW-TO</title>
- </properties>
-
-<body>
-
-
-<section name="Quick-Start Version">
-
- <blockquote><em>
- <p>The description below uses the variable name $CATALINA_HOME
- to refer to the directory into which you have installed Tomcat 4,
- and is the base directory against which most relative paths are
- resolved. However, if you have configured Tomcat 4 for multiple
- instances by setting a CATALINA_BASE directory, you should use
- $CATALINA_BASE instead of $CATALINA_HOME for each of these
- references.</p>
- </em></blockquote>
-
-<p>To install and configure SSL support on Tomcat 4, you need to follow
-these simple steps. For more information, read the rest of this HOW-TO.</p>
-<ol>
-<li>Download JSSE 1.0.2 (or later) from
- <a href="http://java.sun.com/products/jsse/">http://java.sun.com/products/jsse/</a>
- and either make it an <em>installed extension</em> on the system, or else
- set an environment variable <code>JSSE_HOME</code> that points at the
- directory into which you installed JSSE.</li><br/><br/>
-<li>Create a certificate keystore by executing the following command:
-<p>Windows:</p>
-<source>
-%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
-</source>
-<p>Unix:</p>
-<source>
-$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
-</source>
-<p></p>
- and specify a password value of "changeit".</li><br/><br/>
-<li>Uncomment the "SSL HTTP/1.1 Connector" entry in
- <code>$CATALINA_HOME/conf/server.xml</code> and tweak as necessary.</li>
- <br/><br/>
-</ol>
-
-
-</section>
-
-
-<section name="Introduction to SSL">
-
-<p>SSL, or Secure Socket Layer, is a technology which allows web browsers and
-web servers to communicate over a secured connection. This means that the data
-being sent is encrypted by one side, transmitted, then decrypted by the other
-side before processing. This is a two-way process, meaning that both the
-server AND the browser encrypt all traffic before sending out data.</p>
-
-<p>Another important aspect of the SSL protocol is Authentication. This means
-that during your initial attempt to communicate with a web server over a secure
-connection, that server will present your web browser with a set of
-credentials, in the form of a "Certificate", as proof the site is who and what
-it claims to be. In certain cases, the server may also request a Certificate
-from your web browser, asking for proof that <em>you</em> are who you claim
-to be. This is known as "Client Authentication," although in practice this is
-used more for business-to-business (B2B) transactions than with individual
-users. Most SSL-enabled web servers do not request Client Authentication.</p>
-
-</section>
-
-<section name="SSL and Tomcat">
-
-<p>It is important to note that configuring Tomcat to take advantage of
-secure sockets is usually only necessary when running it as a stand-alone
-web server. When running Tomcat primarily as a Servlet/JSP container behind
-another web server, such as Apache or Microsoft IIS, it is usually necessary
-to configure the primary web server to handle the SSL connections from users.
-Typically, this server will negotiate all SSL-related functionality, then
-pass on any requests destined for the Tomcat container only after decrypting
-those requests. Likewise, Tomcat will return cleartext responses, that will
-be encrypted before being returned to the user's browser. In this environment,
-Tomcat knows that communications between the primary web server and the
-client are taking place over a secure connection (because your application
-needs to be able to ask about this), but it does not participate in the
-encryption or decryption itself.</p>
-
-</section>
-
-<section name="Certificates">
-
-<p>In order to implement SSL, a web server must have an associated Certificate
-for each external interface (IP address) that accepts secure connections.
-The theory behind this design is that a server should provide some kind of
-reasonable assurance that its owner is who you think it is, particularly
-before receiving any sensitive information. While a broader explanation of
-Certificates is beyond the scope of this document, think of a Certificate
-as a "digital driver's license" for an Internet address. It states what
-company the site is associated with, along with some basic contact
-information about the site owner or administrator.</p>
-
-<p>This "driver's license" is cryptographically signed by its owner, and is
-therefore extremely difficult for anyone else to forge. For sites involved
-in e-commerce, or any other business transaction in which authentication of
-identity is important, a Certificate is typically purchased from a well-known
-<em>Certificate Authority</em> (CA) such as VeriSign or Thawte. Such
-certificates can be electronically verified -- in effect, the Certificate
-Authority will vouch for the authenticity of the certificates that it grants,
-so you can believe that that Certificate is valid if you trust the Certificate
-Authority that granted it.</p>
-
-<p>In many cases, however, authentication is not really a concern. An
-administrator may simply want to ensure that the data being transmitted and
-received by the server is private and cannot be snooped by anyone who may be
-eavesdropping on the connection. Fortunately, Java provides a relatively
-simple command-line tool, called <code>keytool</code>, which can easily create
-a "self-signed" Certificate. Self-signed Certificates are simply user
-generated Certificates which have not been officially registered with any
-well-known CA, and are therefore not really guaranteed to be authentic at all.
-Again, this may or may not even be important, depending on your needs.</p>
-
-</section>
-
-<section name="General Tips on Running SSL">
-
-<p>The first time a user attempts to access a secured page on your site,
-he or she is typically presented with a dialog containing the details of
-the certificate (such as the company and contact name), and asked if he or she
-wishes to accept the Certificate as valid and continue with the transaction.
-Some browsers will provide an option for permanently accepting a given
-Certificate as valid, in which case the user will not be bothered with a
-prompt each time they visit your site. Other browsers do not provide this
-option. Once approved by the user, a Certificate will be considered valid
-for at least the entire browser session.</p>
-
-<p>Also, while the SSL protocol was designed to be as efficient as securely
-possible, encryption/decryption is a computationally expensive process from
-a performance standpoint. It is not strictly necessary to run an entire
-web application over SSL, and indeed a developer can pick and choose which
-pages require a secure connection and which do not. For a reasonably busy
-site, it is customary to only run certain pages under SSL, namely those
-pages where sensitive information could possibly be exchanged. This would
-include things like login pages, personal information pages, and shopping
-cart checkouts, where credit card information could possibly be transmitted.
-Any page within an application can be requested over a secure socket by
-simply prefixing the address with <code>https:</code> instead of
-<code>http:</code>. Any pages which absolutely <strong>require</strong>
-a secure connection should check the protocol type associated with the
-page request and take the appropriate action of <code>https</code> is not
-specified.</p>
-
-<p>Finally, using name-based virtual hosts on a secured connection can be
-problematic. This is a design limitation of the SSL protocol itself. The SSL
-handshake, where the client browser accepts the server certificate, must occur
-before the HTTP request is accessed. As a result, the request information
-containing the virtual host name cannot be determined prior to authentication,
-and it is therefore not possible to assign multiple certificates to a single
-IP address. If all virtual hosts on a single IP address need to authenticate
-against the same certificate, the addition of multiple virtual hosts should not
-interfere with normal SSL operations on the server. Be aware, however, that
-most client browsers will compare the server's domain name against the domain
-name listed in the certificate, if any (applicable primarily to official,
-CA-signed certificates). If the domain names do not match, these browsers will
-display a warning to the client user. In general, only address-based virtual
-hosts are commonly used with SSL in a production environment.</p>
-
-</section>
-
-<section name="Configuration">
-
-<subsection name="Download and Install JSSE">
-
-<p>Download the <em>Java Secure Socket Extensions</em> (JSSE) package,
-version 1.0.2 or later, from
-<a href="http://java.sun.com/products/jsse/">http://java.sun.com/products/jsse/</a>.
-If you built Tomcat from source, you have probably already downloaded this
-package. If you are running JDK 1.4 (currently in beta), these classes have
-been integrated directly into the JDK, so you can skip this entire step.</p>
-
-<p>After expanding the package, there are two ways to make it available to
-Tomcat (choose one or the other):</p>
-<ul>
-<li>Make JSSE an <em>installed extension</em> by copying all three JAR files
- (<code>jcert.jar</code>, <code>jnet.jar</code>, and <code>jsse.jar</code>)
- into your <code>$JAVA_HOME/jre/lib/ext</code> directory.</li>
-<li>Create a new environment variable <code>JSSE_HOME</code> that contains
- the absolute path to the directory into which you unpacked the
- JSSE binary distribution.</li>
-</ul>
-
-</subsection>
-
-<subsection name="Prepare the Certificate Keystore">
-
-<p>Tomcat currently operates only on <code>JKS</code> format keystores. This
-is Java's standard "Java KeyStore" format, and is the format created by the
-<code>keytool</code> command-line utility. This tool is included in the JDK.
-</p>
-
-<p>To import an existing certificate into a JKS keystore, please read the
-documentation (in your JDK documentation package) about <code>keytool</code>.
-</p>
-
-<p>To create a new keystore from scratch, containing a single self-signed
-Certificate, execute the following from a terminal command line:</p>
-<p>Windows:</p>
-<source>
-%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
-</source>
-<p>Unix:</p>
-<source>
-$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
-</source>
-
-<p>(The RSA algorithm should be preferred as a secure algorithm, and this
-also ensures general compatibility with other servers and components.)</p>
-
-<p>This command will create a new file, in the home directory of the user
-under which you run it, named "<code>.keystore</code>". To specify a
-different location or filename, add the <code>-keystore</code> parameter,
-followed by the complete pathname to your keystore file,
-to the <code>keytool</code> command shown above. You will also need to
-reflect this new location in the <code>server.xml</code> configuration file,
-as described later. For example:</p>
-<p>Windows:</p>
-<source>
-%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA \
- -keystore \path\to\my\keystore
-</source>
-<p>Unix:</p>
-<source>
-$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA \
- -keystore /path/to/my/keystore
-</source>
-
-<p>After executing this command, you will first be prompted for the keystore
-password. The default password used by Tomcat is "<code>changeit</code>"
-(all lower case), although you can specify a custom password if you like.
-You will also need to specify the custom password in the
-<code>server.xml</code> configuration file, as described later.</p>
-
-<p>Next, you will be prompted for general information about this Certificate,
-such as company, contact name, and so on. This information will be displayed
-to users who attempt to access a secure page in your application, so make
-sure that the information provided here matches what they will expect.</p>
-
-<p>Finally, you will be prompted for the <em>key password</em>, which is the
-password specifically for this Certificate (as opposed to any other
-Certificates stored in the same keystore file). You <strong>MUST</strong>
-use the same password here as was used for the keystore password itself.
-(Currently, the <code>keytool</code> prompt will tell you that pressing the
-ENTER key does this for you automatically.)</p>
-
-<p>If everything was successful, you now have a keystore file with a
-Certificate that can be used by your server.</p>
-
-</subsection>
-
-<subsection name="Edit the Tomcat Configuration File">
-
-<p>The final step is to configure your secure socket in the
-<code>$CATALINA_HOME/conf/server.xml</code> file, where
-<code>$CATALINA_HOME</code> represents the directory into which you
-installed Tomcat 4. An example <code><Connector></code> element
-for an SSL connector is included in the default <code>server.xml</code>
-file installed with Tomcat. It will look something like this:</p>
-<source>
-<-- Define an SSL HTTP/1.1 Connector on port 8443 -->
-<!--
-<Connector className="org.apache.catalina.connector.http.HttpConnector"
- port="8443" minProcessors="5" maxProcessors="75"
- enableLookups="true"
- acceptCount="10" debug="0" scheme="https" secure="true">
- <Factory className="org.apache.catalina.net.SSLServerSocketFactory"
- clientAuth="false" protocol="TLS"/>
-</Connector>
--->
-</source>
-
-<p>You will note that the Connector element itself is commented out by default,
-so you will need to remove the comment tags around it. Then, you can
-customize the specified attributes as necessary. For detailed information
-about the various options, consult the
-<a href="config/index.html">Server Configuration Reference</a>. The
-following discussion covers only those attributes of most interest when
-setting up SSL communication.</p>
-
-<p>The <code>port</code> attribute (default value is 8443) is the TCP/IP
-port number on which Tomcat will listen for secure connections. You can
-change this to any port number you wish (such as to the default port for
-<code>https</code> communications, which is 443). However, special setup
-(outside the scope of this document) is necessary to run Tomcat on port
-numbers lower than 1024 on many operating systems.</p>
-
- <blockquote><em>
- <p>If you change the port number here, you should also change the
- value specified for the <code>redirectPort</code> attribute on the
- non-SSL connector. This allows Tomcat to automatically redirect
- users who attempt to access a page with a security constraint specifying
- that SSL is required, as required by the Servlet 2.3 Specification.</p>
- </em></blockquote>
-
-<p>You will notice a <code>Factory</code> element nested inside the
-<code>Connector</code> element. This is where the "socket factory" used
-by Tomcat, whenever it needs a socket on the corresponding port number,
-is configured. You may need to add or change the following attribute
-values, depending on how you configured your keystore earlier:</p>
-
-<table border="1">
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- </tr>
- <tr>
- <td><code>className</code></td>
- <td>The fully qualified class name of the Java class that implements
- this socket factory. Do not change the default value.</td>
- </tr>
- <tr>
- <td><code>clientAuth</code></td>
- <td>Set this value to <code>true</code> if you want Tomcat to require
- all SSL clients to present a client Certificate in order to use
- this socket.</td>
- </tr>
- <tr>
- <td><code>keystoreFile</code></td>
- <td>Add this attribute if the keystore file you created is not in
- the default place that Tomcat expects (a file named
- <code>.keystore</code> in the user home directory under
- which Tomcat is running). You can specify an absolute pathname,
- or a relative pathname that is resolved against the
- <code>$CATALINA_BASE</code> environment variable.</td>
- </tr>
- <tr>
- <td><code>keystorePass</code></td>
- <td>Add this element if you used a different keystore (and Certificate)
- password than the one Tomcat expects (<code>changeit</code>).</td>
- </tr>
- <tr>
- <td><code>protocol</code></td>
- <td>The encryption/decryption protocol to be used on this socket.
- Do not change the default value.</td>
- </tr>
-</table>
-
-<p>After completing these configuration changes, you must restart Tomcat as
-you normally do, and you should be in business. You should be able to access
-any web application supported by Tomcat via SSL. For example, try:</p>
-<source>
-https://localhost:8443
-</source>
-
-<p>and you should see the usual Tomcat splash page (unless you have modified
-the ROOT web application). If this does not work, the following section
-contains some troubleshooting tips.</p>
-
-</subsection>
-
-</section>
-
-<section name="Troubleshooting">
-
-<p>Here is a list of common problems that you may encounter when setting up
-SSL communications, and what to do about them.</p>
-
-<ul>
-
-<li>I get "java.security.NoSuchAlgorithmException" errors in my
- log files.
- <blockquote>
- <p>The JVM cannot find the JSSE JAR files. Follow all of the directions to
- <a href="#Download and Install JSSE">download and install JSSE</a>.</p>
- </blockquote></li>
-
-<li>When Tomcat starts up, I get an exception like
- "java.io.FileNotFoundException: {some-directory}/{some-file} not found".
- <blockquote>
- <p>A likely explanation is that Tomcat cannot find the keystore file
- where it is looking. By default, Tomcat expects the keystore file to
- be named <code>.keystore</code> in the user home directory under which
- Tomcat is running (which may or may not be the same as yours :-). If
- the keystore file is anywhere else, you will need to add a
- <code>keystoreFile</code> attribute to the <code><Factory></code>
- element in the <a href="#Edit the Tomcat Configuration File">Tomcat
- configuration file</a>.</p>
- </blockquote></li>
-
-<li>When Tomcat starts up, I get an exception like
- "java.io.FileNotFoundException: Keystore was tampered with, or
- password was incorrect".
- <blockquote>
- <p>Assuming that someone has not <em>actually</em> tampered with
- your keystore file, the most likely cause is that Tomcat is using
- a different password than the one you used when you created the
- keystore file. To fix this, you can either go back and
- <a href="#Prepare the Certificate Keystore">recreate the keystore
- file</a>, or you can add or update the <code>keystorePass</code>
- attribute on the <code><Factory></code> element in the
- <a href="#Edit the Tomcat Configuration File">Tomcat configuration
- file</a>. <strong>REMINDER</strong> - Passwords are case sensitive!</p>
- </blockquote></li>
-
-</ul>
-
-<p>If you are still having problems, a good source of information is the
-<strong>TOMCAT-USER</strong> mailing list. You can find pointers to archives
-of previous messages on this list, as well as subscription and unsubscription
-information, at
-<a href="http://jakarta.apache.org/site/mail.html">http://jakarta.apache.org/site/mail.html"</a>.</p>
-
-</section>
-
-</body>
-
-</document>
+<?xml version="1.0"?>
+<!DOCTYPE document [
+ <!ENTITY project SYSTEM "project.xml">
+]>
+<document>
+
+ &project;
+
+ <properties>
+ <author email="ccain@apache.org">Christopher Cain</author>
+ <title>SSL Configuration HOW-TO</title>
+ </properties>
+
+<body>
+
+
+<section name="Quick-Start Version">
+
+ <blockquote><em>
+ <p>The description below uses the variable name $CATALINA_HOME
+ to refer to the directory into which you have installed Tomcat 4,
+ and is the base directory against which most relative paths are
+ resolved. However, if you have configured Tomcat 4 for multiple
+ instances by setting a CATALINA_BASE directory, you should use
+ $CATALINA_BASE instead of $CATALINA_HOME for each of these
+ references.</p>
+ </em></blockquote>
+
+<p>To install and configure SSL support on Tomcat 4, you need to follow
+these simple steps. For more information, read the rest of this HOW-TO.</p>
+<ol>
+<li>Download JSSE 1.0.2 (or later) from
+ <a href="http://java.sun.com/products/jsse/">http://java.sun.com/products/jsse/</a>
+ and either make it an <em>installed extension</em> on the system, or else
+ set an environment variable <code>JSSE_HOME</code> that points at the
+ directory into which you installed JSSE.</li><br/><br/>
+<li>Create a certificate keystore by executing the following command:
+<p>Windows:</p>
+<source>
+%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
+</source>
+<p>Unix:</p>
+<source>
+$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
+</source>
+<p></p>
+ and specify a password value of "changeit".</li><br/><br/>
+<li>Uncomment the "SSL HTTP/1.1 Connector" entry in
+ <code>$CATALINA_HOME/conf/server.xml</code> and tweak as necessary.</li>
+ <br/><br/>
+</ol>
+
+
+</section>
+
+
+<section name="Introduction to SSL">
+
+<p>SSL, or Secure Socket Layer, is a technology which allows web browsers and
+web servers to communicate over a secured connection. This means that the data
+being sent is encrypted by one side, transmitted, then decrypted by the other
+side before processing. This is a two-way process, meaning that both the
+server AND the browser encrypt all traffic before sending out data.</p>
+
+<p>Another important aspect of the SSL protocol is Authentication. This means
+that during your initial attempt to communicate with a web server over a secure
+connection, that server will present your web browser with a set of
+credentials, in the form of a "Certificate", as proof the site is who and what
+it claims to be. In certain cases, the server may also request a Certificate
+from your web browser, asking for proof that <em>you</em> are who you claim
+to be. This is known as "Client Authentication," although in practice this is
+used more for business-to-business (B2B) transactions than with individual
+users. Most SSL-enabled web servers do not request Client Authentication.</p>
+
+</section>
+
+<section name="SSL and Tomcat">
+
+<p>It is important to note that configuring Tomcat to take advantage of
+secure sockets is usually only necessary when running it as a stand-alone
+web server. When running Tomcat primarily as a Servlet/JSP container behind
+another web server, such as Apache or Microsoft IIS, it is usually necessary
+to configure the primary web server to handle the SSL connections from users.
+Typically, this server will negotiate all SSL-related functionality, then
+pass on any requests destined for the Tomcat container only after decrypting
+those requests. Likewise, Tomcat will return cleartext responses, that will
+be encrypted before being returned to the user's browser. In this environment,
+Tomcat knows that communications between the primary web server and the
+client are taking place over a secure connection (because your application
+needs to be able to ask about this), but it does not participate in the
+encryption or decryption itself.</p>
+
+</section>
+
+<section name="Certificates">
+
+<p>In order to implement SSL, a web server must have an associated Certificate
+for each external interface (IP address) that accepts secure connections.
+The theory behind this design is that a server should provide some kind of
+reasonable assurance that its owner is who you think it is, particularly
+before receiving any sensitive information. While a broader explanation of
+Certificates is beyond the scope of this document, think of a Certificate
+as a "digital driver's license" for an Internet address. It states what
+company the site is associated with, along with some basic contact
+information about the site owner or administrator.</p>
+
+<p>This "driver's license" is cryptographically signed by its owner, and is
+therefore extremely difficult for anyone else to forge. For sites involved
+in e-commerce, or any other business transaction in which authentication of
+identity is important, a Certificate is typically purchased from a well-known
+<em>Certificate Authority</em> (CA) such as VeriSign or Thawte. Such
+certificates can be electronically verified -- in effect, the Certificate
+Authority will vouch for the authenticity of the certificates that it grants,
+so you can believe that that Certificate is valid if you trust the Certificate
+Authority that granted it.</p>
+
+<p>In many cases, however, authentication is not really a concern. An
+administrator may simply want to ensure that the data being transmitted and
+received by the server is private and cannot be snooped by anyone who may be
+eavesdropping on the connection. Fortunately, Java provides a relatively
+simple command-line tool, called <code>keytool</code>, which can easily create
+a "self-signed" Certificate. Self-signed Certificates are simply user
+generated Certificates which have not been officially registered with any
+well-known CA, and are therefore not really guaranteed to be authentic at all.
+Again, this may or may not even be important, depending on your needs.</p>
+
+</section>
+
+<section name="General Tips on Running SSL">
+
+<p>The first time a user attempts to access a secured page on your site,
+he or she is typically presented with a dialog containing the details of
+the certificate (such as the company and contact name), and asked if he or she
+wishes to accept the Certificate as valid and continue with the transaction.
+Some browsers will provide an option for permanently accepting a given
+Certificate as valid, in which case the user will not be bothered with a
+prompt each time they visit your site. Other browsers do not provide this
+option. Once approved by the user, a Certificate will be considered valid
+for at least the entire browser session.</p>
+
+<p>Also, while the SSL protocol was designed to be as efficient as securely
+possible, encryption/decryption is a computationally expensive process from
+a performance standpoint. It is not strictly necessary to run an entire
+web application over SSL, and indeed a developer can pick and choose which
+pages require a secure connection and which do not. For a reasonably busy
+site, it is customary to only run certain pages under SSL, namely those
+pages where sensitive information could possibly be exchanged. This would
+include things like login pages, personal information pages, and shopping
+cart checkouts, where credit card information could possibly be transmitted.
+Any page within an application can be requested over a secure socket by
+simply prefixing the address with <code>https:</code> instead of
+<code>http:</code>. Any pages which absolutely <strong>require</strong>
+a secure connection should check the protocol type associated with the
+page request and take the appropriate action of <code>https</code> is not
+specified.</p>
+
+<p>Finally, using name-based virtual hosts on a secured connection can be
+problematic. This is a design limitation of the SSL protocol itself. The SSL
+handshake, where the client browser accepts the server certificate, must occur
+before the HTTP request is accessed. As a result, the request information
+containing the virtual host name cannot be determined prior to authentication,
+and it is therefore not possible to assign multiple certificates to a single
+IP address. If all virtual hosts on a single IP address need to authenticate
+against the same certificate, the addition of multiple virtual hosts should not
+interfere with normal SSL operations on the server. Be aware, however, that
+most client browsers will compare the server's domain name against the domain
+name listed in the certificate, if any (applicable primarily to official,
+CA-signed certificates). If the domain names do not match, these browsers will
+display a warning to the client user. In general, only address-based virtual
+hosts are commonly used with SSL in a production environment.</p>
+
+</section>
+
+<section name="Configuration">
+
+<subsection name="Download and Install JSSE">
+
+<p>Download the <em>Java Secure Socket Extensions</em> (JSSE) package,
+version 1.0.2 or later, from
+<a href="http://java.sun.com/products/jsse/">http://java.sun.com/products/jsse/</a>.
+If you built Tomcat from source, you have probably already downloaded this
+package. If you are running JDK 1.4 (currently in beta), these classes have
+been integrated directly into the JDK, so you can skip this entire step.</p>
+
+<p>After expanding the package, there are two ways to make it available to
+Tomcat (choose one or the other):</p>
+<ul>
+<li>Make JSSE an <em>installed extension</em> by copying all three JAR files
+ (<code>jcert.jar</code>, <code>jnet.jar</code>, and <code>jsse.jar</code>)
+ into your <code>$JAVA_HOME/jre/lib/ext</code> directory.</li>
+<li>Create a new environment variable <code>JSSE_HOME</code> that contains
+ the absolute path to the directory into which you unpacked the
+ JSSE binary distribution.</li>
+</ul>
+
+</subsection>
+
+<subsection name="Prepare the Certificate Keystore">
+
+<p>Tomcat currently operates only on <code>JKS</code> format keystores. This
+is Java's standard "Java KeyStore" format, and is the format created by the
+<code>keytool</code> command-line utility. This tool is included in the JDK.
+</p>
+
+<p>To import an existing certificate into a JKS keystore, please read the
+documentation (in your JDK documentation package) about <code>keytool</code>.
+</p>
+
+<p>To create a new keystore from scratch, containing a single self-signed
+Certificate, execute the following from a terminal command line:</p>
+<p>Windows:</p>
+<source>
+%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
+</source>
+<p>Unix:</p>
+<source>
+$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
+</source>
+
+<p>(The RSA algorithm should be preferred as a secure algorithm, and this
+also ensures general compatibility with other servers and components.)</p>
+
+<p>This command will create a new file, in the home directory of the user
+under which you run it, named "<code>.keystore</code>". To specify a
+different location or filename, add the <code>-keystore</code> parameter,
+followed by the complete pathname to your keystore file,
+to the <code>keytool</code> command shown above. You will also need to
+reflect this new location in the <code>server.xml</code> configuration file,
+as described later. For example:</p>
+<p>Windows:</p>
+<source>
+%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA \
+ -keystore \path\to\my\keystore
+</source>
+<p>Unix:</p>
+<source>
+$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA \
+ -keystore /path/to/my/keystore
+</source>
+
+<p>After executing this command, you will first be prompted for the keystore
+password. The default password used by Tomcat is "<code>changeit</code>"
+(all lower case), although you can specify a custom password if you like.
+You will also need to specify the custom password in the
+<code>server.xml</code> configuration file, as described later.</p>
+
+<p>Next, you will be prompted for general information about this Certificate,
+such as company, contact name, and so on. This information will be displayed
+to users who attempt to access a secure page in your application, so make
+sure that the information provided here matches what they will expect.</p>
+
+<p>Finally, you will be prompted for the <em>key password</em>, which is the
+password specifically for this Certificate (as opposed to any other
+Certificates stored in the same keystore file). You <strong>MUST</strong>
+use the same password here as was used for the keystore password itself.
+(Currently, the <code>keytool</code> prompt will tell you that pressing the
+ENTER key does this for you automatically.)</p>
+
+<p>If everything was successful, you now have a keystore file with a
+Certificate that can be used by your server.</p>
+
+</subsection>
+
+<subsection name="Edit the Tomcat Configuration File">
+
+<p>The final step is to configure your secure socket in the
+<code>$CATALINA_HOME/conf/server.xml</code> file, where
+<code>$CATALINA_HOME</code> represents the directory into which you
+installed Tomcat 4. An example <code><Connector></code> element
+for an SSL connector is included in the default <code>server.xml</code>
+file installed with Tomcat. It will look something like this:</p>
+<source>
+<-- Define an SSL HTTP/1.1 Connector on port 8443 -->
+<!--
+<Connector className="org.apache.catalina.connector.http.HttpConnector"
+ port="8443" minProcessors="5" maxProcessors="75"
+ enableLookups="true"
+ acceptCount="10" debug="0" scheme="https" secure="true">
+ <Factory className="org.apache.catalina.net.SSLServerSocketFactory"
+ clientAuth="false" protocol="TLS"/>
+</Connector>
+-->
+</source>
+
+<p>You will note that the Connector element itself is commented out by default,
+so you will need to remove the comment tags around it. Then, you can
+customize the specified attributes as necessary. For detailed information
+about the various options, consult the
+<a href="config/index.html">Server Configuration Reference</a>. The
+following discussion covers only those attributes of most interest when
+setting up SSL communication.</p>
+
+<p>The <code>port</code> attribute (default value is 8443) is the TCP/IP
+port number on which Tomcat will listen for secure connections. You can
+change this to any port number you wish (such as to the default port for
+<code>https</code> communications, which is 443). However, special setup
+(outside the scope of this document) is necessary to run Tomcat on port
+numbers lower than 1024 on many operating systems.</p>
+
+ <blockquote><em>
+ <p>If you change the port number here, you should also change the
+ value specified for the <code>redirectPort</code> attribute on the
+ non-SSL connector. This allows Tomcat to automatically redirect
+ users who attempt to access a page with a security constraint specifying
+ that SSL is required, as required by the Servlet 2.3 Specification.</p>
+ </em></blockquote>
+
+<p>You will notice a <code>Factory</code> element nested inside the
+<code>Connector</code> element. This is where the "socket factory" used
+by Tomcat, whenever it needs a socket on the corresponding port number,
+is configured. You may need to add or change the following attribute
+values, depending on how you configured your keystore earlier:</p>
+
+<table border="1">
+ <tr>
+ <th>Attribute</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><code>className</code></td>
+ <td>The fully qualified class name of the Java class that implements
+ this socket factory. Do not change the default value.</td>
+ </tr>
+ <tr>
+ <td><code>clientAuth</code></td>
+ <td>Set this value to <code>true</code> if you want Tomcat to require
+ all SSL clients to present a client Certificate in order to use
+ this socket.</td>
+ </tr>
+ <tr>
+ <td><code>keystoreFile</code></td>
+ <td>Add this attribute if the keystore file you created is not in
+ the default place that Tomcat expects (a file named
+ <code>.keystore</code> in the user home directory under
+ which Tomcat is running). You can specify an absolute pathname,
+ or a relative pathname that is resolved against the
+ <code>$CATALINA_BASE</code> environment variable.</td>
+ </tr>
+ <tr>
+ <td><code>keystorePass</code></td>
+ <td>Add this element if you used a different keystore (and Certificate)
+ password than the one Tomcat expects (<code>changeit</code>).</td>
+ </tr>
+ <tr>
+ <td><code>protocol</code></td>
+ <td>The encryption/decryption protocol to be used on this socket.
+ Do not change the default value.</td>
+ </tr>
+</table>
+
+<p>After completing these configuration changes, you must restart Tomcat as
+you normally do, and you should be in business. You should be able to access
+any web application supported by Tomcat via SSL. For example, try:</p>
+<source>
+https://localhost:8443
+</source>
+
+<p>and you should see the usual Tomcat splash page (unless you have modified
+the ROOT web application). If this does not work, the following section
+contains some troubleshooting tips.</p>
+
+</subsection>
+
+</section>
+
+<section name="Troubleshooting">
+
+<p>Here is a list of common problems that you may encounter when setting up
+SSL communications, and what to do about them.</p>
+
+<ul>
+
+<li>I get "java.security.NoSuchAlgorithmException" errors in my
+ log files.
+ <blockquote>
+ <p>The JVM cannot find the JSSE JAR files. Follow all of the directions to
+ <a href="#Download and Install JSSE">download and install JSSE</a>.</p>
+ </blockquote></li>
+
+<li>When Tomcat starts up, I get an exception like
+ "java.io.FileNotFoundException: {some-directory}/{some-file} not found".
+ <blockquote>
+ <p>A likely explanation is that Tomcat cannot find the keystore file
+ where it is looking. By default, Tomcat expects the keystore file to
+ be named <code>.keystore</code> in the user home directory under which
+ Tomcat is running (which may or may not be the same as yours :-). If
+ the keystore file is anywhere else, you will need to add a
+ <code>keystoreFile</code> attribute to the <code><Factory></code>
+ element in the <a href="#Edit the Tomcat Configuration File">Tomcat
+ configuration file</a>.</p>
+ </blockquote></li>
+
+<li>When Tomcat starts up, I get an exception like
+ "java.io.FileNotFoundException: Keystore was tampered with, or
+ password was incorrect".
+ <blockquote>
+ <p>Assuming that someone has not <em>actually</em> tampered with
+ your keystore file, the most likely cause is that Tomcat is using
+ a different password than the one you used when you created the
+ keystore file. To fix this, you can either go back and
+ <a href="#Prepare the Certificate Keystore">recreate the keystore
+ file</a>, or you can add or update the <code>keystorePass</code>
+ attribute on the <code><Factory></code> element in the
+ <a href="#Edit the Tomcat Configuration File">Tomcat configuration
+ file</a>. <strong>REMINDER</strong> - Passwords are case sensitive!</p>
+ </blockquote></li>
+
+</ul>
+
+<p>If you are still having problems, a good source of information is the
+<strong>TOMCAT-USER</strong> mailing list. You can find pointers to archives
+of previous messages on this list, as well as subscription and unsubscription
+information, at
+<a href="http://jakarta.apache.org/site/mail.html">http://jakarta.apache.org/site/mail.html"</a>.</p>
+
+</section>
+
+</body>
+
+</document>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>