RE: Question on HTTPConnector.

[mettu . kumar]

Craig,

Thanks for clarification. I do agree with you given the three options the one 
choosen by tomcat group is the best one(Option one).
But there need to be an option for tomcat users to use option 3 in case where 
DOS issues are solved by some other means (ex: using a switch which does the same).
HttpConnector.java has following lines:
/**
 * The maximum number of processors allowed, or <0 for unlimited.
 */
private int maxProcessors = 20;

Which gives an impression if maxProcessors  is set to a -ve value in server.xml 
unlimited option is used. But this is not implemented. 
A way to test this is set minProcessors="0" maxProcessors="-1". You will notice that 
server is not responding for request.


Kumar.


-Original Message-
From: Craig R. McClanahan [mailto:[EMAIL PROTECTED]]
Sent: Saturday, July 07, 2001 5:45 PM
To: [EMAIL PROTECTED]
Subject: Re: Question on HTTPConnector.




On Sat, 7 Jul 2001 [EMAIL PROTECTED] wrote:

> 
> Looking at org.apache.catalina.connector.http.HTTPConnector I got a
> question regarding the way its implemented.(I am looking at 4.0b3 src)
> 
> 
> Look at this block of code(in run method of HTTPConnector):
>   // Hand this socket off to an appropriate processor
>   HttpProcessor processor = createProcessor();
>   if (processor == null) {
>   try {
>   log(sm.getString("httpConnector.noProcessor"));
>   socket.close();
>   } catch (IOException e) {
>   ;
>   }
>   continue;
>   }
> 
> As per my understanding if no. of HTTPConnections == maxProcessors(
> parameter in server.xml), when a new HTTPRequest comes server just
> closes the Socket with any wait period.

Yes, that's exactly what happens.

> Isn't this Bad? In cases where
> Load suddenly increases this could cause problems.
> 

Well yes, it's bad, but so will any other reaction.  What choices are
there in handling it?

(1) Current behavior of closing the connection and go back to
accepting new connections (causes a client-side protocol error)

(2) Pause and try again in a bit (but in the mean time, this
thread cannot accept any new connections, so they stack up
inside the server socket up to acceptCount and then start
getting refused)

(3) Ignore the maxProcessors parameter and create a new processor (and
its associated thread) anyway (can lead to denial of service attacks)

Have you a suggestion on how we might deal with this more effectively?

The real key is to configure maxProcessors to the maximum number of
simultaneous requests you want your server to handle, based on the
hardware capabilities and the processing requirements of your
application.  For example, if your response time starts going through the
roof once you exceed N simultaneous requests (because you've encountered
some sort of bottleneck), it doesn't make sense to set maxProcessors
higher than N -- that will just cause response times to slow down for
everyone.

> 
> Any info on this is greatly appreciated.
> 
> Thanks,
> Kumar.
> 

Craig

cvs commit: jakarta-tomcat-connectors/webapp .cvsignore

[pier]

pier01/07/07 20:34:22

  Modified:webapp   .cvsignore
  Log:
  Added APR to .CVSIGNORE
  
  Revision  ChangesPath
  1.2   +2 -0  jakarta-tomcat-connectors/webapp/.cvsignore
  
  Index: .cvsignore
  ===
  RCS file: /home/cvs/jakarta-tomcat-connectors/webapp/.cvsignore,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- .cvsignore2001/05/12 04:54:52 1.1
  +++ .cvsignore2001/07/08 03:34:21 1.2
  @@ -1,3 +1,5 @@
  +.DS_Store
  +apr
   Makefile
   Makedefs
   configure
  
  
  

cvs commit: jakarta-tomcat-connectors/webapp buildconf.sh configure.in

[pier]

pier01/07/07 20:32:07

  Modified:webapp   buildconf.sh configure.in
  Log:
  First part of the new build method. More tomorrow morning.
  
  Revision  ChangesPath
  1.2   +5 -0  jakarta-tomcat-connectors/webapp/buildconf.sh
  
  Index: buildconf.sh
  ===
  RCS file: /home/cvs/jakarta-tomcat-connectors/webapp/buildconf.sh,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- buildconf.sh  2001/05/12 04:42:32 1.1
  +++ buildconf.sh  2001/07/08 03:32:07 1.2
  @@ -6,4 +6,9 @@
   # the "configure.in". If you check these sources out of CVS,
   # you will need to execute this script first.
   
  +if [ ! -d ./apr ]
  +then
  +mkdir apr
  +echo "Don't a forget to put a copy of the APR sources in `pwd`/apr/"
  +fi
   autoconf
  
  
  
  1.8   +81 -48jakarta-tomcat-connectors/webapp/configure.in
  
  Index: configure.in
  ===
  RCS file: /home/cvs/jakarta-tomcat-connectors/webapp/configure.in,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- configure.in  2001/07/02 14:06:00 1.7
  +++ configure.in  2001/07/08 03:32:07 1.8
  @@ -58,65 +58,56 @@
   dnl -
   dnl Author  Pier Fumagalli 
   dnl Author  Jon S. Stevens 
  -dnl Version $Id: configure.in,v 1.7 2001/07/02 14:06:00 jfclere Exp $
  +dnl Version $Id: configure.in,v 1.8 2001/07/08 03:32:07 pier Exp $
   dnl -
   
   dnl -
   dnl Initialize GNU AutoConf
   dnl -
  -sinclude(../common/build/apache.m4)dnl
   AC_INIT(Makefile.in)
   
   dnl -
  -dnl Check out CC and RANLIB programs
  +dnl Define the local functions we're going to use
   dnl -
  -AC_PROG_CC
  -AC_PROG_RANLIB
  -
  -AC_PATH_PROG(AR,ar,$PATH)dnl
  -AC_PATH_PROG(TEST,test,$PATH)dnl
  +AC_DEFUN(LOCAL_HEADER,[
  +printf "\n\033\13301;31m%s\033\13300m\n" "$1" 1>&2
  +AC_PROVIDE([$0])
  +])
   
  -AC_SUBST(AR)
  -AC_SUBST(TEST)
  +AC_DEFUN(LOCAL_FILTEREXEC,[{
  +$1
  +echo RETVAL $?
  +}|{
  +RET=0
  +while ${TRUE}
  +do
  +read FIRST LINE
  +if ${TEST} ! "$?" -eq "0"
  +then
  +break
  +else
  +if ${TEST} "$FIRST" = "RETVAL"
  +then
  +RET="$LINE"
  +else
  +printf "\033\13301m%s\033\13300m: %s\n" "$2" "$FIRST $LINE" 1>&2
  +fi
  +fi
  +done
  +unset FIRST
  +unset LINE
  +}])
   
   dnl -
  -dnl Process the --with-apr=... command line argument (required)
  +dnl Check out ranlib and ar
   dnl -
  -AC_MSG_CHECKING([APR directory])
  -AC_ARG_WITH(apr,
  - [  --with-apr=DIR  where the APR installation can be found [required]],
  - APRDIR=$withval,
  - APRDIR="")
  -if ${TEST} -z "$APRDIR" ; then
  - AC_MSG_ERROR([Required command line argument \"--with-apr=...\" not specified])
  -fi
  -if ${TEST} ! -d "$APRDIR" ; then
  - AC_MSG_ERROR([Invalid APR directory \"$APRDIR\" specified])
  -fi
  -if ${TEST} ! -f "$APRDIR/include/apr.h" ; then
  - AC_MSG_ERROR([No APR headers in \"$APRDIR\"])
  -fi
  -for i in "$APRDIR/lib/libapr*"
  -do
  -if ${TEST} -f "$i" ; then
  -has_apr_lib = true
  -break
  -fi
  -done
  -if ${TEST} ${has_apr_lib} ; then
  - AC_MSG_ERROR([No APR libraries in \"$APRDIR\"])
  -fi
  -
  -CURDIR=`pwd`
  -cd $APRDIR
  -APRDIR=`pwd`
  -cd $CURDIR
  -AC_MSG_RESULT($APRDIR)
  -AC_SUBST(APRDIR)
  -
  -TGTDIRS="lib"
  -AC_MSG_RESULT([setting target directories to \"$TGTDIRS\"])
  -AC_SUBST(TGTDIRS)
  +AC_PROG_RANLIB
  +AC_PATH_PROG(AR,ar,${PATH})
  +AC_PATH_PROG(TEST,test,$PATH)
  +AC_PATH_PROG(TRUE,true,$PATH)
  +AC_SUBST(AR)
  +AC_SUBST(TEST)
  +AC_SUBST(TRUE)
   
   dnl -
   dnl Process the --with-apxs[=FILE]... command line argument
  @@ -188,9 +179,51 @@
   AC_MSG_RESULT($TGTDIR)
   AC_SUBST(TGTDIR)
   
  +dnl -
  +dnl Process the --with-apr=... command line argument (required)
  +dnl -
  +AC_MSG_CHECKING([APR directory])
  +AC_ARG_WITH(apr,
 

'_' <-> 0x5f and Jasper

[Keith Wannamaker]

Is there a known problem with jsp filenames containing '_'?
The Jasper in jakarta-tomcat head compiles 'foo_bar.jsp' to
'foo_0005fbar.jsp' for me.  Clearly there is some escaping 
gone awry, but surely I'm not the first to encounter this?
I'm digging into it now...
Keith

RE: Question on HTTPConnector.

[mettu . kumar]

Donald,

I believe this is logged. See the following lines of code:
if (processor == null) {
try {
log(sm.getString("httpConnector.noProcessor"));
socket.close();
} catch (IOException e) {
;
}

Kumar.  


-Original Message-
From: Donald Ball [mailto:[EMAIL PROTECTED]]
Sent: Saturday, July 07, 2001 7:16 PM
To: [EMAIL PROTECTED]
Subject: Re: Question on HTTPConnector.


On Sat, 7 Jul 2001, Craig R. McClanahan wrote:

> Well yes, it's bad, but so will any other reaction.  What choices are
> there in handling it?
>
> (1) Current behavior of closing the connection and go back to
> accepting new connections (causes a client-side protocol error)
>
> (2) Pause and try again in a bit (but in the mean time, this
> thread cannot accept any new connections, so they stack up
> inside the server socket up to acceptCount and then start
> getting refused)
>
> (3) Ignore the maxProcessors parameter and create a new processor (and
> its associated thread) anyway (can lead to denial of service attacks)
>
> Have you a suggestion on how we might deal with this more effectively?

shouldn't this event be logged? it would be nice if this happened too
frequently for a warning to be sent to the server's administrator.

- donald

Re: Question on HTTPConnector.

[Donald Ball]

On Sat, 7 Jul 2001, Craig R. McClanahan wrote:

> Well yes, it's bad, but so will any other reaction.  What choices are
> there in handling it?
>
> (1) Current behavior of closing the connection and go back to
> accepting new connections (causes a client-side protocol error)
>
> (2) Pause and try again in a bit (but in the mean time, this
> thread cannot accept any new connections, so they stack up
> inside the server socket up to acceptCount and then start
> getting refused)
>
> (3) Ignore the maxProcessors parameter and create a new processor (and
> its associated thread) anyway (can lead to denial of service attacks)
>
> Have you a suggestion on how we might deal with this more effectively?

shouldn't this event be logged? it would be nice if this happened too
frequently for a warning to be sent to the server's administrator.

- donald

RE: First day - RE: PROPOSAL: Tomcat docs

[Rob S.]

> See my post "DOC: Table of Contents" for more details.  (More details than
> you want, probably :-)

Not a lot of comments so far... I guess Monday morning =)

- r

Re: Question on HTTPConnector.

[Craig R. McClanahan]

On Sat, 7 Jul 2001 [EMAIL PROTECTED] wrote:

> 
> Looking at org.apache.catalina.connector.http.HTTPConnector I got a
> question regarding the way its implemented.(I am looking at 4.0b3 src)
> 
> 
> Look at this block of code(in run method of HTTPConnector):
>   // Hand this socket off to an appropriate processor
>   HttpProcessor processor = createProcessor();
>   if (processor == null) {
>   try {
>   log(sm.getString("httpConnector.noProcessor"));
>   socket.close();
>   } catch (IOException e) {
>   ;
>   }
>   continue;
>   }
> 
> As per my understanding if no. of HTTPConnections == maxProcessors(
> parameter in server.xml), when a new HTTPRequest comes server just
> closes the Socket with any wait period.

Yes, that's exactly what happens.

> Isn't this Bad? In cases where
> Load suddenly increases this could cause problems.
> 

Well yes, it's bad, but so will any other reaction.  What choices are
there in handling it?

(1) Current behavior of closing the connection and go back to
accepting new connections (causes a client-side protocol error)

(2) Pause and try again in a bit (but in the mean time, this
thread cannot accept any new connections, so they stack up
inside the server socket up to acceptCount and then start
getting refused)

(3) Ignore the maxProcessors parameter and create a new processor (and
its associated thread) anyway (can lead to denial of service attacks)

Have you a suggestion on how we might deal with this more effectively?

The real key is to configure maxProcessors to the maximum number of
simultaneous requests you want your server to handle, based on the
hardware capabilities and the processing requirements of your
application.  For example, if your response time starts going through the
roof once you exceed N simultaneous requests (because you've encountered
some sort of bottleneck), it doesn't make sense to set maxProcessors
higher than N -- that will just cause response times to slow down for
everyone.

> 
> Any info on this is greatly appreciated.
> 
> Thanks,
> Kumar.
> 

Craig

Re: First day - RE: PROPOSAL: Tomcat docs

[guru]

On Sat, Jul 07, 2001 at 09:37:55AM -0700, Craig R. McClanahan wrote:
> 
> We might not need to spend as much time on the generic "how to build a web
> application" stuff, now that other resources are available -- and focus on
> the stuff that is important for configuration, like all the stuff that
> goes into server.xml.

I agree.  There's already plenty of Servlets/Webapps documentation,
including your App Dev Guide.

I see the need for the following documents:

Standalone Installation Guide

Installation Behind a Web Server Guide

Administrator's Guide

Developing Tomcat Guide


See my post "DOC: Table of Contents" for more details.  (More details than
you want, probably :-)

-- 
Alex Chaffee   mailto:[EMAIL PROTECTED]
jGuru - Java News and FAQs http://www.jguru.com/alex/
Creator of Gamelan http://www.gamelan.com/
Founder of Purple Technology   http://www.purpletech.com/
Curator of Stinky Art Collective   http://www.stinky.com/

RE: cvs commit: jakarta-tomcat/src/share/org/apache/tomcat/modules/generators ErrorHandler.java

[Ignacio J. Ortega]

Hola Larry:

This code along with some other ( related to SetHookFinder ) .. breaks
completely TC33 auth.., as the Status handler is called recursively ..
First with a 401 and later a 302... 

So i'm getting a error loop message in whenever i try the security
examples..

Any idea on how to fix it  ?

Saludos ,
Ignacio J. Ortega


> -Mensaje original-
> De: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED]]
> Enviado el: viernes 6 de julio de 2001 20:41
> Para: [EMAIL PROTECTED]
> Asunto: cvs commit:
> jakarta-tomcat/src/share/org/apache/tomcat/modules/generators
> ErrorHandler.java
> 
> 
> larryi  01/07/06 11:41:02
> 
>   Modified:src/share/org/apache/tomcat/modules/generators
> ErrorHandler.java
>   Log:
>   Fix recursive error handling if web.xml maps error code 404 
> to a non-existent
>   JSP page. With this fix, no response will be sent if status 
> handler is called
>   recursively. You will need to examine the log output to see 
> the error.
>   
>   If web.xml maps error code 404 to a non-existent html, use 
> default "not found"
>   handler instead of default "status" handler.
>   
>   Revision  ChangesPath
>   1.14  +19 -3 
> jakarta-tomcat/src/share/org/apache/tomcat/modules/generators/
> ErrorHandler.java
>   
>   Index: ErrorHandler.java
>   ===
>   RCS file: 
> /home/cvs/jakarta-tomcat/src/share/org/apache/tomcat/modules/g
> enerators/ErrorHandler.java,v
>   retrieving revision 1.13
>   retrieving revision 1.14
>   diff -u -r1.13 -r1.14
>   --- ErrorHandler.java   2001/07/05 20:40:45 1.13
>   +++ ErrorHandler.java   2001/07/06 18:41:00 1.14
>   @@ -191,8 +191,15 @@
>   }
>
>   boolean isDefaultHandler = false;
>   +if ( statusLoop( ctx, req ) ){
>   +log( "Error loop for " + req + " error code " + code);
>   +return;
>   +}
>   if( errorServlet==null ) {
>   -   errorServlet=ctx.getServletByName( "tomcat.statusHandler");
>   +if( code == 404 )
>   +errorServlet=ctx.getServletByName( 
> "tomcat.notFoundHandler");
>   +else
>   +errorServlet=ctx.getServletByName( 
> "tomcat.statusHandler");
>   isDefaultHandler = true;
>   }
>
>   @@ -389,9 +396,18 @@
>   }
>   return false;
>}
>   -
>   -
>
>   +/** Handle the case of status handler generating an error
>   + */
>   +private boolean statusLoop( Context ctx, Request req ) {
>   +if ( 
> req.getAttribute("javax.servlet.error.status_code") != null ) {
>   +if( ctx.getDebug() > 0 )
>   +ctx.log( "Error: nested error inside 
> status servlet " +
>   +
> req.getAttribute("javax.servlet.error.status_code"));
>   +return true;
>   +}
>   +return false;
>   +}
>
>}
>
>   
>   
>   
> 

Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu mentation Redactors To Hire]

[Pier Fumagalli]

Quoting Aaron Bannert <[EMAIL PROTECTED]>:
> 
> d) jakarta-tomcat-connectors (* Pier is working on this, I've
> submitted

Hold it... Pier is working on the new build for the WebApp Module, and the 
documentation related to it... I never said I'm going to take care of the 
documentation of all jakarta-tomcat-connectors :) :) :)

Pier

Question on HTTPConnector.

[mettu . kumar]

Looking at org.apache.catalina.connector.http.HTTPConnector I got a question regarding 
the way its implemented.(I am looking at 4.0b3 src)


Look at this block of code(in run method of HTTPConnector):
// Hand this socket off to an appropriate processor
HttpProcessor processor = createProcessor();
if (processor == null) {
try {
log(sm.getString("httpConnector.noProcessor"));
socket.close();
} catch (IOException e) {
;
}
continue;
}

As per my understanding if no. of HTTPConnections == maxProcessors( parameter in 
server.xml), when a new HTTPRequest comes server just closes the Socket with any wait 
period. Isn't this Bad? In cases where Load suddenly increases this could cause 
problems.


Any info on this is greatly appreciated.

Thanks,
Kumar.

Re: problem with redirects when using tomcat-4.0b5 and mod_jk (fwd)

[Donald Ball]

On Sat, 7 Jul 2001, Donald Ball wrote:

> i've seen no responses to this issue. does anyone have any suggestions?
>
> - donald

i thought i'd go ahead and take a gander at helping myself. after futilely
trying to get catalina running in a debugger on linux (can anyone else do
this?), i resorted to good ol' System.err and patched HttpResponseBase:

private String toAbsolute(String location) {
if (location == null)
return (location);
// Construct a new absolute URL if possible (cribbed from
// the DefaultErrorPage servlet)
URL url = null;
try {
url = new URL(location);
} catch (MalformedURLException e1) {
HttpServletRequest hreq =
(HttpServletRequest) request.getRequest();
String requrl = HttpUtils.getRequestURL(hreq).toString();
System.err.println("REQURL: "+requrl);
try {
url = new URL(new URL(requrl), location);
} catch (MalformedURLException e2) {
throw new IllegalArgumentException(location);
}
}
return (url.toString());

}

and i found the the request url that it's having trouble with is:

https://foobar.webslingerZ.com/foobar/login

apparantly, java.net.URL can't parse this because it doesn't recognize
https as a protocol! i've got a couple of workarounds in mind, but before
i kludge together a patch, is there anything else i can do to fix this?
adding the jsse library doesn't seem to help, but maybe the https protocol
handler needs to be registered?

- donald

problem with redirects when using tomcat-4.0b5 and mod_jk (fwd)

[Donald Ball]

i've seen no responses to this issue. does anyone have any suggestions?

- donald

-- Forwarded message --
Date: Thu, 5 Jul 2001 22:37:26 -0400 (EDT)
From: Donald Ball <[EMAIL PROTECTED]>
To: [EMAIL PROTECTED]
Subject: problem with redirects when using tomcat-4.0b5 and mod_jk

hey guys. i'm getting a problem with redirects when i use tomcat-4.0b5 and
mod_jk with the ajp13 connector. my stacktrace is as follows:

Error creating the
resourcejava.lang.IllegalArgumentExceptiontables/trouble_ticket_table/query?clause=active&clause=for-employeejava.lang.IllegalArgumentException:
tables/trouble_ticket_table/query?clause=active&clause=for-employeejava.lang.IllegalArgumentException:
tables/trouble_ticket_table/query?clause=active&clause=for-employeejava.lang.IllegalArgumentException:
tables/trouble_ticket_table/query?clause=active&clause=for-employee at
org.apache.catalina.connector.HttpResponseBase.toAbsolute(HttpResponseBase.java:673)
at
org.apache.catalina.connector.HttpResponseBase.encodeRedirectURL(HttpResponseBase.java:925)
at
org.apache.catalina.connector.HttpResponseFacade.encodeRedirectURL(HttpResponseFacade.java:122)
at
org.apache.cocoon.environment.http.HttpResponse.encodeRedirectURL(HttpResponse.java:76)
at
org.apache.cocoon.environment.http.HttpEnvironment.redirect(HttpEnvironment.java:99)
at

the url is, in fact, valid, and it works great with tomcat-4.0b5 with the
http connector. note i'm using mod_jk built from the jtc cvs repository
from about a week ago since the current cvs won't build. does anyone have
any suggestions?

- donald

RE: tomcat docs mailinglists..

[Martin van den Bemt]

Ehh.. an extra note : My server is still subject to change and needs a
restart of apache so now and then, but qmail will keep on running during my
webserver down time.. (i'm running on an ADSL connection, so that is also
not guaranteed to be up at all times)..

Mvgr,
Martin

tomcat docs mailinglists..

[Martin van den Bemt]

Hi,

I created a few mailinglist on my server tomcatdocs.isallineed.org , to send
notes for tomcat documentation to. This is just to gather all the notes on a
specific subject to make  documentation from.

Why did I do this? If I fixed something or got something running, found an
issue while upgrading etc,etc, you don't have the time to write everything
down. The information is present in your gray mass upstairs,  but if you
need to create documentation you cannot remember that specific little thing
anymore. I normally start notepad, type it in and save it to be never found
again. If you just write an e-mail to eg
[EMAIL PROTECTED], it will be stored, so your
grandchildren can still enjoy your knowledge and other people (maby me, or
someone else who wants to do it), can gather that information once in a
while and update the docs, faq, tips,etc,etc...
Hope not only me and Thomas Bezdicek like the idea, but other people too..
These mailinglist are not a replacement for a future mailinglist on apache
on tomcat documentation (if it is gonna be created), so it's not a
discussion forum
(I will make one if someone thinks that it is usefull).

Suggestions for the subject line :

tomcatversion (if applicable) eg T4.0B5
other details devided by a - eg. -windows-upgrade-tc33
subject : the subject of the note

If someone has a better idea or a format that is better parseable to a faq
or documentation, please let me know, so I can write that parser ;-)

For now I created the following mailinglists :
connectors
dev
faq
install
tips
users

See http://tomcatdocs.isallineed.org if you don't have a clue where to put
your note..
Just mail to @tomcatdocs.isallineed.org
subsribing can be done with :
[EMAIL PROTECTED]
unsubscribing can be done with
[EMAIL PROTECTED]

You don't have to subscribe to the mailinglist to send mails to that
list (and it is not moderated at the moment, but I will check once a
week or something to see if there is rubbish in the mailinglist).

Hope it is usefull and else : why not use it anyway.

Mvgr,
Martin van den Bemt

Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]

[Craig R. McClanahan]

On Sat, 7 Jul 2001, Aaron Bannert wrote:

> On Sat, Jul 07, 2001 at 09:25:46AM -0700, Craig R. McClanahan wrote:
> > Yes, we obviously need pointers in a top-level README on "where the docs
> > went".
> 
> I'm willing to collaborate on these types of docs. On a slight tangent,
> I'd like to point out that we could use more STATUS and README documents,
> if only to serve the purpose of a signpost for current and new developers.
> 
> *Every* CVS module that is a work-in-progress should have some sort of
> STATUS document, as well as a README describing what the repository
> contains. The first serves as a road map for any new developers who
> want to get into the source. The second serves as a roadmap for new
> builders/testers who want to know what the heck they're looking at.
> 
> 
> > Also, on my list of "high level" desires, I forgot to include one:
> > 
> > * All of the Tomcat documentation should be visible online at the Tomcat
> >   web site.
> > 
> > which can (at least partially) deal with Alex's "how do you set up the
> > VCR" issue :-).
> 
> ( s/Alex/Aaron/ :)
> 

Sorry about that ... too many "A-list" people today :-)

> That will partially satisfy me, but not everyone has fully-connected
> high-speed internet access and graphical browsers (at least not while
> they're trying to get Tomcat working). I'd still like to push for plain
> text documentation for each of the following:
> 
> 0) README and STATUS in each of
>  a) jakarta-tomcat-4.0
>  b) jakarta-regexp
>  c) jakarta-servletapi-4
>  d) jakarta-tomcat-connectors (* Pier is working on this, I've submitted
>  the beginnings of a README)
>  e) "the various TC3.x repositories that I'm less familiar with"
> 
> 1) build instructions for each. Not extensive, just simple bootstrapping
> instructions, maybe even just in the README.
> 
> 2) [basic] configuration instructions. Again, not extensive, but enough
> to get it up. Maybe a recipe that would answer questions like:
>  a) What goes in server.xml?
>  b) How do I start/stop TC?
>  c) What must be already installed in order to run TC? (JDK version, etc...)
> 

It definitely makes sense to have enough "how to get started" stuff in
plain text README form to get a newbie going.

Hmm, if we can transform XML->HTML, maybe we can just use a different
stylesheet (or set of Anakia macros) and transform XML->TXT as well .

> 
> Who's with me on this? I can submit an outline for each and let the people
> with more experience fill in the blanks.
> 
> 
> > > 2) Why have the docs as a web app?  I'm not sure I see the benefits yet,
> > > aside from being able to have a pointer to the docs from the ROOT/index
> > > page.
> > > 
> > 
> > A couple of reasons:
> > 
> > * Because we already do -- and it's quite convenient to be able to
> >   look at the docs once you get Tomcat started the first time.  The
> >   problem today is that we are really overloading the ROOT web app,
> >   and it's not particularly well organized.
> 
> I totally agree that it is convenient, but it may be harder for us to
> realize the difficulty in getting this beast rolling the first time
> from our altitude. We want every college student who has ever had any
> interest in Servlets/JSP running this thing on their home Linux/*BSD/WinXX
> (*gag*) machine, and they're only going to do that if the barrier to
> entry is well defined.
> 

As a side comment on this topic, Tomcat 4 installation and administration
is going to directly benefit from Sun's JavaOne announcement about the Web
Services Pack (which will include Tomcat).  In particular, my team at Sun
is going to put some serious developer hours into these areas, and the
vast majority of the resulting code will work just fine for a stand-alone
download of Tomcat from Apache as well.

By the way, one of the current XML docs
(catalina/docs/dev/xdocs/fs-admin-apps.xml) is a proposed set of high
level functional requirements for administrative apps for Tomcat 4.
Developers interested in this topic are encouraged to read it and
suggest improvements.

Sun is also increasing the number of folks writing and executing tests of
Tomcat 4 features (beyond the issues of spec compliance).  In order to do
this, the test writers need a description of what correct behavior is --
so one of the things I will personally be working on is "functional
specs" type docs for the various existing features (such as the fs-*.xml
files in the same directory as the admin apps doc).  That's why I'm quite
happy to see a discussion about documentation formats and tools happen
now.  The net result will be a substantial increase in the amount of
useful "internals" documentation about how Tomcat 4 is put together.

> -aaron
> 
> 

Craig

Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu mentation Redactors To Hire]

[Aaron Bannert]

On Sat, Jul 07, 2001 at 09:25:46AM -0700, Craig R. McClanahan wrote:
> Yes, we obviously need pointers in a top-level README on "where the docs
> went".

I'm willing to collaborate on these types of docs. On a slight tangent,
I'd like to point out that we could use more STATUS and README documents,
if only to serve the purpose of a signpost for current and new developers.

*Every* CVS module that is a work-in-progress should have some sort of
STATUS document, as well as a README describing what the repository
contains. The first serves as a road map for any new developers who
want to get into the source. The second serves as a roadmap for new
builders/testers who want to know what the heck they're looking at.


> Also, on my list of "high level" desires, I forgot to include one:
> 
> * All of the Tomcat documentation should be visible online at the Tomcat
>   web site.
> 
> which can (at least partially) deal with Alex's "how do you set up the
> VCR" issue :-).

( s/Alex/Aaron/ :)

That will partially satisfy me, but not everyone has fully-connected
high-speed internet access and graphical browsers (at least not while
they're trying to get Tomcat working). I'd still like to push for plain
text documentation for each of the following:

0) README and STATUS in each of
 a) jakarta-tomcat-4.0
 b) jakarta-regexp
 c) jakarta-servletapi-4
 d) jakarta-tomcat-connectors (* Pier is working on this, I've submitted
 the beginnings of a README)
 e) "the various TC3.x repositories that I'm less familiar with"

1) build instructions for each. Not extensive, just simple bootstrapping
instructions, maybe even just in the README.

2) [basic] configuration instructions. Again, not extensive, but enough
to get it up. Maybe a recipe that would answer questions like:
 a) What goes in server.xml?
 b) How do I start/stop TC?
 c) What must be already installed in order to run TC? (JDK version, etc...)


Who's with me on this? I can submit an outline for each and let the people
with more experience fill in the blanks.


> > 2) Why have the docs as a web app?  I'm not sure I see the benefits yet,
> > aside from being able to have a pointer to the docs from the ROOT/index
> > page.
> > 
> 
> A couple of reasons:
> 
> * Because we already do -- and it's quite convenient to be able to
>   look at the docs once you get Tomcat started the first time.  The
>   problem today is that we are really overloading the ROOT web app,
>   and it's not particularly well organized.

I totally agree that it is convenient, but it may be harder for us to
realize the difficulty in getting this beast rolling the first time
from our altitude. We want every college student who has ever had any
interest in Servlets/JSP running this thing on their home Linux/*BSD/WinXX
(*gag*) machine, and they're only going to do that if the barrier to
entry is well defined.

-aaron

Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]

[Craig R. McClanahan]

On Sat, 7 Jul 2001 [EMAIL PROTECTED] wrote:

> On Fri, Jul 06, 2001 at 10:06:21PM -0700, Craig R. McClanahan wrote:
> > 
> > * Docs should live in the source tree of the project that they
> >   are about.  Although Henri's suggestion for jakarta-tomcat-docs
> >   is noble, what you'll find in practice is that there is very little
> >   documentation that is relevant across multiple versions of Tomcat.
> 
> That remains to be seen.  My gut tells me the opposite.  I'm thinking
> connectors, classpath issues (though some details are different with
> Catalina, a lot are the same),

Although the concepts of the issues above are similar, the details are
very different.

> web.xml docs, authentication,

These are the same because they are application-related (i.e. portable
because of the servlet spec) not Tomcat-related.  In principle, anything
we write about this should apply to any servlet container.

> performance-tuning a web app...

That's a huge area, and may be somewhat ambitious.  But, again, most of
this would be portable to any servlet container, not just Tomcat.

> I'd love to get your input on the
> outline I just posted if you get around to it -- tell me which
> sections are definitely different between 3 and 4.
> 

Could you repost the most recent version of the proposed outline?  My
delete key got a little sticky, and I accidentally deleted the most recent
version last night.

Just for interest's sake, here's the list of "user" things in Tomcat 4.0
that are new (relative to 3.2), cribbed from my JavaOne talk:
* Access logs (web-server style)
* CGI support
* Configurable realms at Engine, Host, and Context levels, including
  JNDIRealm.
* Container-managed security (DIGEST and CLIENT-CERT modes,
  plus single sign on support)
* "Default Context" configuration
* HTTP/1.1 support in stand-alone mode
* JNDI naming context support (including support for configuring
   and  mappings, JDBC connection pooling,
  and extensible object factories).
* "Manager" web app
* MOD_WEBAPP
* Request filtering valves (accept/deny based on client hostname
  or IP address)
* Run directly from war file
* Server side includes (*.shtml)
* User web apps (http://www.mycompany.com/~craigmcc)

Now, picture yourself installing Tomcat 3.2 (because it's the current
production version).  Do you *really* want to wade through the docs on all
of the above, which is totally irrelevant to your needs, just because we
put the docs for all versions in one file?  To say nothing about all the
things that were present in 3.2 but are configured differently in 4.0 ...

> The current situation with the docs on the site for 3.2 and 3.3
> illustrate the problem with fragmenting two doc trees that are
> actually very similar.

Nearly everything important about configuring Tomcat is different
anyway.  The only "common" stuff is the App Dev Guide.  As has been
discussed, that probably makes sense in a common docs directory (until you
have do decide whether or not to cover both versions of the specs --
servlet 2.2/2.3 and JSP 1.1/1.2 -- in the same docs :-).  But, if it's
separate, you've also got to figure out how you're going to "release" it.

>  Any reorganization or new docs or error fixing
> will need to be propagated back to the 3.2 branch,

Why?

The code is in maintenance mode -- I don't see a problem with the docs
being in maintenance mode as well.

Of course, anyone who *wants* to do this is welcome to do so, but I don't
see it as a prerequisite.

> which will be a
> terror to maintain.  I feel the same thing could easily happen with
> 4.0 vs 4.1 in the near future.
> 

Not if we get started with a nice disciplined source directory
structure.  That's why this discussion is so timely.

Not when you remember that the 4.0->4.1 changes won't be a complete
rearchitecting (at least to the extent that people listen to me :-), the
way that 3.2->3.3 turned out to be.

Not when you remember that 4.0 will go into maintenance mode when 4.1 is
released, so we can focus energies (both code and docs) on the current
version.

But 4.1 *will* be different than 4.0.  So there will need to be a way
to produce the docs for 4.1 *only* -- by that time, users won't care how
4.0 worked, either.

IMHO, trying to mix docs for multiple versions in the same document set
is a receipie for disaster -- for reasons that I articulated last
night, plus the fact that people only care about the version they are
installing.

It's fine to have "comparative features" sorts of docs in some separate
(common) docs repository, along with the App Dev Guide type stuff that is
also common.  But that's maybe three-to-five pages worth of stuff -- good,
comprehensive docs on something like Tomcat is going to be more in the low
hundreds of pages (depending, of course, on how fine-grained we decide to 
make it), for any given version.

> > * The files that are checked in should only be the XML sources, *not* the
> >   generated files.  This varies from what Jon set up in jakarta-site2,
> >

Vote on oustanding doc issues?

[Rob S.]

Not to be pushy or anything, but I'd like to get these settled quickly so we
can get down to writing some docs =)  Does a committer want to call a vote
on these two things?  Are we ready to do that yet?

1) Tomcat documentation per-project or in a single repository?

2) What is the format (XML, *Book, HTML, etc.) of the documentation source?
If XML, what DTD?

Okay, you can't really vote on the second I one I guess =)  Hmm...  what to
do?  Personally I'd like to use something XML-like, but close to HTML.  It
would require less documentation (re: tags) and less work than HTML to
author docs, meaning hopefully more people would do it, more often.  If
that's Anakia, whatever.  If it's XML with some other DTD, whatever.

Once we know these two things, we can get to work.  Of course there will be
discussion on these points, but I'd like to bring them to a close sooner
than later, so we can keep moving on with things like the TOC.

- r

RE: First day - RE: PROPOSAL: Tomcat docs

[Craig R. McClanahan]

On Sat, 7 Jul 2001, Rob S. wrote:

> > One decision to be made when actually *writing* this thing is whether you
> > consider the servlet spec to be a "required reading" prerequisite or
> > not.  I'd certainly vote for that, but you'll find that the current App
> > Developer's Guide does cover quite a bit (but not all) of the material
> > from the spec.
> 
> If not the spec, at LEAST the dev's guide...
> 

Another consideration is the relative priority of the Web App Developer's
Guide (or whatever it ends up being called) is the priority of this doc,
versus the other config docs.

When I originally wrote the App Dev Guide, servlet 2.2 was still pretty
new, and the concepts of a web app were foreign to most folks.  Now,
however, the recent versions of the servlet books cover the same territory
pretty well -- and many of them are using Tomcat as their server in the
examples and tutorials.

We might not need to spend as much time on the generic "how to build a web
application" stuff, now that other resources are available -- and focus on
the stuff that is important for configuration, like all the stuff that
goes into server.xml.

> - r
> 
> 

RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:[TomcatDocumentation Redactors To Hire]

[Craig R. McClanahan]

On Sat, 7 Jul 2001, Rob S. wrote:

> Unfortunatly, I won't be able to participate much in this discussion this
> weekend since i know *0* about AWT and the Java cert (Monday morning, 9am)
> apparently thinks you should =)  Sorry all...
> 
> > The important issue is *not* what transformation tool is used.  The
> 
> Oh, by "works for Catalina" I was stating that TC4 is already using the
> tool; why not continue using it?
> 

TC4 is not currently using Anakia (which is the tool I thought you were
talking about).  It's using Ant's 

RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]

[Craig R. McClanahan]

On Sat, 7 Jul 2001, Rob S. wrote:

> > Providing Tomcat documentation in a WAR file is a little like providing
> > a VHS tape on how to setup your VCR. It may seem really elegant to have
> > on-the-fly style-generating documentation, and I may be alone on this,
> > but I think that the majority of the user-oriented documentation should
> > just be plain text. (By 'user-oriented documentation' I specifically
> > mean build instructions and deployment configuration docs).
> 
> It would be in a WAR file as HTML.  The build would do the transformation
> and create the WAR file.
> 
> Two things:
> 
> 1) Users may be confused as to "where the docs went" if they don't see a
> /docs directory.  Solution (one of many): have /docs/readme.txt with a
> pointer back to /INSTALL.txt.  A quick-install guide would be pretty
> short...
> 

Yes, we obviously need pointers in a top-level README on "where the docs
went".

Also, on my list of "high level" desires, I forgot to include one:

* All of the Tomcat documentation should be visible online at the Tomcat
  web site.

which can (at least partially) deal with Alex's "how do you set up the
VCR" issue :-).

> 2) Why have the docs as a web app?  I'm not sure I see the benefits yet,
> aside from being able to have a pointer to the docs from the ROOT/index
> page.
> 

A couple of reasons:

* Because we already do -- and it's quite convenient to be able to
  look at the docs once you get Tomcat started the first time.  The
  problem today is that we are really overloading the ROOT web app,
  and it's not particularly well organized.

* Implicitly, I think we've been agreeing that the *output* format is
  HTML.  Using plain text just doesn't cut it when you want to create
  links to other portions of the docs, or include images beyond what
  you can do in ASCII art.  In essence, a web app is just a documentation
  directory with a little extra stuff (WEB-INF/*) that is not really much
  different than any other project that chooses HTML format for its docs.
  It's just in "webapps/docs" instead of "docs" in the binary distro.

> - r
> 
> 

Craig

Latest status of virtual domains..

[Martin van den Bemt]

Hi,

I've seen (actually not read, it wasn't an issue at that moment) a lot of
mails about virtual hosting. Since I'm gonna start setting up a lot if
virtual hosts (all on 1 ip address btw..) with apache (not a problem) and in
combination with tomcat, my question is what the status is and what needs
testing, explenation etc,etc,etc.. Which parts of the sources to study when
something isn't working the way I expected etc, which connectors need
testing or which connectors work, etc) At least I can put together new docs
on how to set it up in certain situations.. So if you want to use my time on
this.. please do.. Please also provide which versions need testing (have
3.2.x , 3.3 and an older version of tomcat 4, I would prefer to look at the
3.X versions though, since the server is gonna be "production"...).

My goal is trying to achieve a Waldorf and Statler experience :

Booh, Booh, that was the worst thing I ever seen
It was terrible
Well it wasn't that bad, o yeah?
There were parts that I liked
Yeah I liked a lot of it
Yeah it was good
Yeah it was great
It was wonderfull
Ah, bravo
More More..

If you get my drift ;-))

Mvgr,
Martin van den Bemt

RE: Example Not Working: Is it Tomcat, my naieve installation or the Example?

[Marc Saegesser]

This has already been fixed in the Tomcat 3.2.3-dev.  Try the latest nightly
build and verify that it works for you.

Marc Saegesser

> -Original Message-
> From: Hamish MacEwan [mailto:[EMAIL PROTECTED]]
> Sent: Thursday, July 05, 2001 8:23 PM
> To: [EMAIL PROTECTED]
> Subject: Example Not Working: Is it Tomcat, my naieve installation or
> the Example?
>
>
> Hi,
>
> This problem has been reported on tomcat-user, but no fix or explanation
> has been forthcoming, and it's very confusing for the new Tomcat user
> deciding if the flaw is in their configuration, Tomcat, or in fact the
> set up of the examples.
>
> It's probably trivial, but some attention to this might make
> using/learning about Tomcat a lot more successful by either explaining,
> fixing or removing the problem.  I'm not bitching or unaware of the
> demands on all our time, and I'm extraordinarily grateful for the
> programmes you provide, but ...
>
> The problem is described in detail here:
>
> http://mikal.org/interests/java/tomcat/archive/view?mesg=24751
>
> I appreciate always the "as-is" expectation of software in this
> development methodology, but a known flaw like this is a terrible
> barrier to the novice who may, as I have done, spend days trying to
> resolve it, notify lists, search archives, email developers and the
> original poster, all over something which may not have any significance
> at all.
>
> My interest is in SOAP, but until I'm confident of the container,
> servlets are too scary to contemplate.
>
> Thank you for any help you may be able to provide.
>
> Hamish.

RE: JDBC Realm Questions Tomcat 3.2.2

[Jonathan Pierce]

Craig,

Thanks for providing such a complete explanation of Realms. I was confused
about configuring data sources and connection pooling .vs. JDBC Realms for
authentication.

I'm going to try out Tomcat 4.0 and configure some datasources and access
them via jndi lookup.

I'm also planning on taking a look at using PoolMan
(http://www.codestudio.com/) with Tomcat3.2.2 since it looks like it,
like Tomcat 4.0, also lets you configure datasources in an xml file and
provides a connection pooling implementation.

Jonathan


-Original Message-
From: Craig R. McClanahan [mailto:[EMAIL PROTECTED]]
Sent: Saturday, July 07, 2001 1:52 AM
To: [EMAIL PROTECTED]
Cc: [EMAIL PROTECTED]
Subject: Re: JDBC Realm Questions Tomcat 3.2.2


On Tue, 3 Jul 2001, Jonathan Pierce wrote:

> This may be a stupid question but I've found hundreds of messages from
confused
> users on the subject of JDBC Realms and Tomcat and no good explanation or
> example. There is a documentation file JDBCRealm.howto but it doesn't
describe
> how to instantiate the datasource with a code example or what additional
> property files need to be included to configure jndi properties.
>
> Like lots of other people, I'm trying to use the release Tomcat 3.2.2,
configure
> multiple jdbc datasources in the server.xml file, and reference it in my
> servlet. I am only interested in using a shared database ID to connect to
the
> database for all users of my servlet. The database connect info needs to
be in
> Tomcat conf files since the passwords need to be reconfigured at
deployment time
> outside my war file.
>
> 1. Is this behavior supported by Tomcat 3.2.2? How do I configure multiple
> database datasources and instantiate them in my code?
>

IIRC, Tomcat 3.2.2 only supports a single realm of usernames and passwords
for all of the webapps running in a single JVM.  That is not the case with
4.0.

> 2. Assuming I setup the datasources like below, what properties do I use
to
> assign a name to the datasource so I can reference it?
>
>  className="org.apache.tomcat.request.JDBCRealm"
> debug="99"
> driverName="oracle.jdbc.driver.OracleDriver"
> connectionURL="jdbc:oracle:thin:@ntserver:1521:ORCL"
> connectionName="scott"
> connectionPassword="tiger"
> />
>
>  className="org.apache.tomcat.request.JDBCRealm"
> debug="99"
> driverName="oracle.jdbc.driver.OracleDriver"
> connectionURL="jdbc:oracle:thin:@ntserver2:1521:ORCL"
> connectionName="scott"
> connectionPassword="tiger"
> />
>
>
> 3. What do I need to add to a config file in order to access the initial
context
> so I can retrieve the datasource?
>
> import javax.servlet.*;
> import javax.servlet.http.*;
> import javax.naming.*;
> import javax.sql.*;
>
> String  theDataSourceName = "???";
> String  theNamingProviderURL = "???";
> String  theInitialContextNamingFactory = "???";
> Properties theProperties = new Properties ();
> theProperties.put("java.naming.provider.url", theNamingProviderURL);
>
theProperties.put("java.naming.factory.initial",theInitialContextNamingFacto
ry);
>
> Context theInitialContext = new InitialContext(theProperties);
> DataSource theDataSource = (DataSource) theInitialContext.lookup
> (theDatasourceName);
>

You might be confusing realms with datasources :-)

The purpose of JDBCRealm is to allow you to store the usernames,
passwords, and roles required for container-managed security (as described
in the servlet spec) in a database accessed via JDBC.  When used in this
manner, only Tomcat talks to the database that you configure with
JDBCRealm -- not your application.

If you want to use a datasource for your own application data, you don't
need JDBCRealm at all.  Instead, you've got a couple choices:

* Use one of the existing datasource implementations, following the
  configuration documentation included with that datasource.

* Use a J2EE application server, where you can declare a
   in the web.xml file, and use your app server's
  deployment tools to connect that to an actual database.

* Use Tomcat 4.0, which lets you do the same thing -- the connection
  to a particular database is done in the "conf/server.xml" file.

Craig McClanahan

RE: First day - RE: PROPOSAL: Tomcat docs

[Rob S.]

> One decision to be made when actually *writing* this thing is whether you
> consider the servlet spec to be a "required reading" prerequisite or
> not.  I'd certainly vote for that, but you'll find that the current App
> Developer's Guide does cover quite a bit (but not all) of the material
> from the spec.

If not the spec, at LEAST the dev's guide...

- r

RE: Tomcat Documentation Project

[Rob S.]

+1 to everything, esp "docs in same project"

- r

> -Original Message-
> From: Craig R. McClanahan [mailto:[EMAIL PROTECTED]]
> Sent: Saturday, July 07, 2001 1:42 AM
> To: [EMAIL PROTECTED]
> Subject: Re: Tomcat Documentation Project
>
>
>
>
> On Tue, 3 Jul 2001, Alex Chaffee wrote:
>
> > Leaving aside the issue of file format for just one second...
> >
> > Are we agreed on the following?
> >
> > 1. Tomcat documentation sucks :-)
> >
> > 2. There needs to be a new CVS project called jakarta-tomcat-doc.
> >
> > My reasoning is that we want to avoid the fragmentation of
> documentation
> > into different trees for 3.2, 3.3, and 4.0.  Why?  Because a lot of
> > documentation would apply equally to all versions.
> >
>
> This is not at *all* clear to me.  For developer-oriented docs, the
> overlap would seem to be zero -- the architectures of all three
> environments are radically different.  For user docs, there are
> *similarities* between the versions, but they are by no means identical --
> for example, IMHO it would be very confusing to have a single document
> about JDBCRealm (just to pick an example) with three different ways to
> configure it, based on which Tomcat version you are using.  To say nothing
> about the fact that the various versions of JDBCRealm are *not* identical
> in their functionality or implementation.
>
> And, many of the concepts you want to talk about in configuration docs are
> *radically* different between versions.
>
> +1 for separate doc trees per version (with a possible exception
> identified in the next paragraph).
>
> > Looking at it in reverse, the fact that someone is using an old version
> > of Tomcat shouldn't mean they're forced to use an old version of the
> > documentation.  Instead, a chapter on, say, web application deployment
> > may need to have a sidebar describing changes between 3.x and 4.x, but
> > assuming 4.x isn't *radically* different, they can both use the same
> > core text. (In cases where 4.x *is* radically different, it would just
> > have a separate document/chapter, with the 4.x specificity clearly
> > labelled in the title.)
> >
>
> The "Application Developer's Guide" is pretty much the only existing doc
> that is 99.9% portable across 3.2/3.3/4.0.  That's courtesy of the fact
> that it talks about web apps as defined in the servlet spec, and touches
> only very lightly on anything that is Tomcat-version-specific.
>
> There is probably 50% overlap if you talk about something like mod_jk
> (i.e. the stuff about configuring httpd.conf).  At that point, IMHO, it's
> still better to have separate docs from a readability point of view.
>
> But the killer issue is that the various versions are created by different
> groups of developers, with different release schedules.  Nobody is going
> to be willing to wait for the omnibus documentation to be updated, or care
> about shipping docs covering the "other" versions -- so you can count on
> anything about the 3.3 version to be out-of-date in the 4.0 release
> (for example), and vice versa.
>
> Note that none of the above is influenced much by whether docs are stored
> in a separate jakarta-tomcat-doc CVS repository or not (my preference is
> "not" but that's a minor detail).  But, even if it's all in the same
> repository, in practice it's going to end up being separate
> subdirectories, maintained and released indepently, anyway.
>
> > I know the 4.x crew have begun the process of creating a separate
> > documentation set, including xdocs, and this is great. If it's too much
> > work to integrate 3.x and 4.x then maybe they should remain
> separate CVS
> > projects too, but it may still be desirable to have a separate CVS
> > project anyway.
> >
>
> The more work you make it for developers to write docs along with code,
> the less docs are going to get written (by those developers).  If the docs
> are written by others it's not that big a deal -- but I personally like
> the docs I write in the same CVS repository as the code that the docs
> describe.
>
> > 3. There needs to be a better index/TOC for the documentation we do
> > have, and a reorganization of the redundant / outdated / wrong parts of
> > the existing docs (the Apache config stuff comes to mind).
> >
> > 4. Someone or some small group of people should take responsibility for
> > making this happen (before we "run out of steam"), regularly submitting
> > proposals and keeping the rest of the group apprised of
> developments and
> > decisions, but retaining some authority. Let's call this person/people
> > the Documentation Czar. I'm not proposing he/they have any real
> > authority over the content, but just over organizing it, deciding where
> > to place it, and forming "to do" lists for documents/chapters that need
> > to be written or proofed or tech edited or revised.
> >
> > If we agree on the above, then there's a good chance I'd
> volunteer to be
> > the Doc Czar, even though I think it's a lot of work. I've been
> managing
>

RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]

[Rob S.]

Unfortunatly, I won't be able to participate much in this discussion this
weekend since i know *0* about AWT and the Java cert (Monday morning, 9am)
apparently thinks you should =)  Sorry all...

> The important issue is *not* what transformation tool is used.  The

Oh, by "works for Catalina" I was stating that TC4 is already using the
tool; why not continue using it?

> * Docs should live in the source tree of the project that they
>   are about.  Although Henri's suggestion for jakarta-tomcat-docs
>   is noble, what you'll find in practice is that there is very little
>   documentation that is relevant across multiple versions of Tomcat.

I have a feeling that whatever is the same will be a lot of piecemeal here
and there, excluding of course, web-app documentation.  So far yourself,
Pier, and Henri are the only three TC developers to post their position on
that (re: inter-version relevancy).  Personally, I don't think there should
be a separate project, but I think I've already said that a few times =)

> * The files that are checked in should only be the XML sources, *not* the
>   generated files.  This varies from what Jon set up in jakarta-site2,
>   based on long and drawn out earlier discussions (same issues as those
>   surrounding checking JAR files into CVS :-).

Someone will have to setup something that exposes the latest generated
documentation on the Jakarta www site.  It's being done already for Struts,
so I guess that won't be a big problem.

> * At least two documentation webapps (developer-oriented and
>   user-oriented) would seem to be appropriate.  Having more than two

"developer" as in "web" or "Tomcat"?  I'm not sure why separating the doc
into two packages helps - perhaps I'm missing some obvious benefit trying to
think at 7:15am =)

- r

RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu mentation Redactors To Hire]

[Rob S.]

> Providing Tomcat documentation in a WAR file is a little like providing
> a VHS tape on how to setup your VCR. It may seem really elegant to have
> on-the-fly style-generating documentation, and I may be alone on this,
> but I think that the majority of the user-oriented documentation should
> just be plain text. (By 'user-oriented documentation' I specifically
> mean build instructions and deployment configuration docs).

It would be in a WAR file as HTML.  The build would do the transformation
and create the WAR file.

Two things:

1) Users may be confused as to "where the docs went" if they don't see a
/docs directory.  Solution (one of many): have /docs/readme.txt with a
pointer back to /INSTALL.txt.  A quick-install guide would be pretty
short...

2) Why have the docs as a web app?  I'm not sure I see the benefits yet,
aside from being able to have a pointer to the docs from the ROOT/index
page.

- r

Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu mentation Redactors To Hire]

[guru]

On Fri, Jul 06, 2001 at 10:06:21PM -0700, Craig R. McClanahan wrote:
> 
> * Docs should live in the source tree of the project that they
>   are about.  Although Henri's suggestion for jakarta-tomcat-docs
>   is noble, what you'll find in practice is that there is very little
>   documentation that is relevant across multiple versions of Tomcat.

That remains to be seen.  My gut tells me the opposite.  I'm thinking
connectors, classpath issues (though some details are different with
Catalina, a lot are the same), web.xml docs, authentication,
performance-tuning a web app... I'd love to get your input on the
outline I just posted if you get around to it -- tell me which
sections are definitely different between 3 and 4.

The current situation with the docs on the site for 3.2 and 3.3
illustrate the problem with fragmenting two doc trees that are
actually very similar.  Any reorganization or new docs or error fixing
will need to be propagated back to the 3.2 branch, which will be a
terror to maintain.  I feel the same thing could easily happen with
4.0 vs 4.1 in the near future.

> * The files that are checked in should only be the XML sources, *not* the
>   generated files.  This varies from what Jon set up in jakarta-site2,
>   based on long and drawn out earlier discussions (same issues as those
>   surrounding checking JAR files into CVS :-).

+1

.xml = .java, .html = .class
./build.sh docs would generate the html directory


-- 
Alex Chaffee   mailto:[EMAIL PROTECTED]
jGuru - Java News and FAQs http://www.jguru.com/alex/
Creator of Gamelan http://www.gamelan.com/
Founder of Purple Technology   http://www.purpletech.com/
Curator of Stinky Art Collective   http://www.stinky.com/