head	1.8;
access;
symbols
	ApacheJSSI-1_1_2:1.8
	ApacheJSSI-1_1_1:1.7
	ApacheJSSI-pre1_1:1.5
	JavaApacheSSI-pre2-1_1:1.1.2.3
	jservssi_1_1-DEV:1.1.0.2;
locks; strict;
comment	@# @;


1.8
date	99.06.22.23.07.12;	author hzeller;	state Exp;
branches;
next	1.7;

1.7
date	99.06.22.10.47.38;	author hzeller;	state Exp;
branches;
next	1.6;

1.6
date	99.06.16.23.08.09;	author hzeller;	state Exp;
branches;
next	1.5;

1.5
date	99.06.10.11.39.14;	author hzeller;	state Exp;
branches;
next	1.4;

1.4
date	99.06.10.11.21.14;	author hzeller;	state Exp;
branches;
next	1.3;

1.3
date	99.06.10.10.19.56;	author hzeller;	state Exp;
branches;
next	1.2;

1.2
date	99.06.09.22.41.18;	author hzeller;	state Exp;
branches;
next	1.1;

1.1
date	99.05.29.06.27.57;	author hzeller;	state dead;
branches
	1.1.2.1;
next	;

1.1.2.1
date	99.05.29.06.27.57;	author hzeller;	state Exp;
branches;
next	1.1.2.2;

1.1.2.2
date	99.05.29.17.05.38;	author hzeller;	state Exp;
branches;
next	1.1.2.3;

1.1.2.3
date	99.05.29.22.30.52;	author hzeller;	state Exp;
branches;
next	1.1.2.4;

1.1.2.4
date	99.06.05.12.17.33;	author hzeller;	state Exp;
branches;
next	;


desc
@@


1.8
log
@o 1.1.1 -> 1.1.2
@
text
@
		          A P A C H E   J S S I
                              Version 1.1.2

		       Installation Instructions

                   -- see docs/install.html as well --

   Compiling
   ---------
     
     You need to have the Java Servlet API (JSDK) 2.0 in your CLASSPATH to 
     compile Apache JSSI. Please get this from: 
     <http://java.sun.com/products/servlet/>

     To compile the source code, go to the src/java directory and
     type:

     $ make
	
     you'll get ApacheJSSI.jar
     
     If you grabbed the distribution, the ApacheJSSI.jar is already 
     compiled for you.

  Installing
  ----------

       Apache JServ
       ------------
       In order to include the Apache JSSI classes in your servlet 
       engine, you have to enable the server side inclusion by mapping the 
       ".jhtml" URI to the "org.apache.servlet.ssi.SSI" servlet by doing 
       the following:

       In your Apache config file add:
         ApJServAction .jhtml /servlets/org.apache.servlet.ssi.SSI

       Change the /servlets/ part to be the location of your zone.

       In your zone.properties file add:
         repositories=/path/to/ApacheJSSI.jar

       Change the /path/to/ part to be the path to the location of your 
       ApacheJSSI.jar file.

       If you would like to use the URL-Rewriting feature, use the
       org.apache.servlet.ssi.ParameterPropagatingSSI - Servlet instead.
       Consult the HTML-documentation for further information.

       Other Servlet Engines
       ---------------------
       Apache JSSI will work with other servlet engines that meet the 
       requirements defined above. Please see the Apache JServ installation 
       instructions for hints on how to configure your servlet engine in 
       order to do suffix/action mapping.
 
       Servlet Parameters
       ------------------
       The SSI Servlet understands some optional parameters which can 
       be given in the init Arguments:

       o SSISiteRoot (path)
         In order to use traditional SSI directives (&lt;!--#..),
         pass the following init argument to the "org.apache.servlet.ssi.SSI" 
         servlet (by following your servlet engine instructions):

            SSISiteRoot=/site/root

         Replace /site/root by the top level directory of your site.
         This is the DocumentRoot in your Apache 
         configuration file.

         Beware, the SSI directives are not (yet) fully implemented.

       o expires     (integer)
         SSI documents usually contain dynamic content and thus shouldn't
         be cached by clients. With the 'expires' parameter you
         can give the number of seconds after the generated document
         should be considered stale. Use negative values to prevent
         caching (expiration in the past).
         This sets the 'Expires' header (RFC2068, 14.21).

       o compresslarge  (size in Bytes)
         - experimental -
         If the output becomes larger than the given number
         of bytes, it is compressed. 
	 The size of the output which decides whether deflation
	 is used or not is a heuristic value based on the size of the 
	 last generated pagesizes. It is a weighted mean value:	  
	 1/2*(size of lastpage) + 1/4*(size of the page before) + 1/8*...
         First call of the page will not be compressed.

         Output is only compressed if the browser supplies the
         Accept-Encoding Header. Supported compress algorithms are
         gzip and compress.
	 NOTE that compression uses CPU cycles and takes a bit of
	 time. So using this option may not make much sense for the
	 intranet but may be useful for pages larger than
	 several 10s kBs served to the internet.
	 See the output of your access_log for result: typical
	 pages become 5-10 times smaller with compression.

         This evaluates the Accept-Encoding header and
         sets the Content-Encoding and
         Vary headers (RFC2068, 14.3, 14.12, 14.43).

       o buffered  ("yes"|"no")
         Buffer the Output of the SSI servlet. This is needed if you 
	 want to set headers within in the included servlets which 
	 should affect the whole output. Use this if you need to set 
	 headers (i.e. cookies, esp. if you want to use cookie based 
	 session handling; see documentation of your servlet engine). 
	 Another feature is, that output is a bit faster than without 
	 buffering if you have many 'active' places in the Page, 
	 e.g. doing URL rewriting with the ParameterPropagatingSSI.

	 Drawbacks are, that this uses a bit more memory (the whole page 
	 output is buffered) which in turn is work for the garbage 
	 collector. And you've to wait until the whole page is created 
	 which may make you feel that it's indeed slower ..

	 Since the buffered output allows to determine the pagesize, this
	 options sets the Content-Length header (RFC2068, 14.14).

       o debug ("yes"|"no")
         - default no -
         Logs how long it took to process the page to the servlet log. Useful if you want to
         experiment with the 'compresslarge' and 'buffered' options to 
         see how it effects processing.

       o charset (String containing the charset)
         - default none -
         Set the charset.

         This option modifies the Content-Type Header. Usually, this is
         set to "text/html", with the charset attribute its something like e.g.
         "text/html; charset=koi8-r" (RFC2068, 14.18).

       o PropagateParameters (';'-seperated stringlist)
         - ParameterPropagatingSSI only - 
	 Semicolon seperated list of parameters to be propagated.
	 See HTML document describing this servlet.


       With Apache JServ, you just have to insert a line in your
       zone.properties file go apply these parameters:

       Example:
       servlet.org.apache.servlet.ssi.SSI.initArgs=SSISiteRoot=/site/root, \
						   expires=-1000
  
                                           The Java Apache Project
                                           <http://java.apache.org/>
@


1.7
log
@o changed version 1.1 -> 1.1.1 in docs
@
text
@d3 1
a3 1
                              Version 1.1.1
@


1.6
log
@o add 'debug' - init parameter in order to be able to switch if JSSI logs
  the processing time
o add 'charset' parameter as denoted by <michael@@geocom.ru>
@
text
@d3 1
a3 1
                              Version 1.1
@


1.5
log
@o its 'repositories' not 'repository' ; and in INSTALL it was completely
  wrong: wrapper.classpath (seems to be a bit ancient ..)
@
text
@d126 14
@


1.4
log
@o Rename Java Apache SSI to Apache JSSI; 'Java' is a SUN tm.
@
text
@d42 1
a42 1
         wrapper.classpath=/path/to/ApacheJSSI.jar
@


1.3
log
@o fixed typo
@
text
@d2 1
a2 1
		      J A V A   A P A C H E   S S I
d13 1
a13 1
     compile Java Apache SSI. Please get this from: 
d21 1
a21 1
     you'll get JavaApacheSSI.jar
d23 1
a23 1
     If you grabbed the distribution, the JavaApacheSSI.jar is already 
d31 1
a31 1
       In order to include the Java Apache SSI classes in your servlet 
d42 1
a42 1
         wrapper.classpath=/path/to/JavaApacheSSI.jar
d45 1
a45 1
       JavaApacheSSI.jar file.
d53 1
a53 1
       Java Apache SSI will work with other servlet engines that meet the 
@


1.2
log
@o merge the 'jservssi_1_1-DEV' - branch with the default branch
@
text
@d91 1
a91 1
	 1/2*(size of lastpage) + 1/8*(size of the page before) + 1/4*...
@


1.1
log
@file INSTALL was initially added on branch jservssi_1_1-DEV.
@
text
@d1 140
@


1.1.2.1
log
@o add a way to control client caching: the new 'expires' init argument
  for the servlet allows for providing a time after the generated
  content expires. Negative values can prevent caching completely.
  ('Expires'-Header: RFC2068, 14.21)
@
text
@a0 96

		      J A V A   A P A C H E   S S I
                              Version 1.1

		       Installation Instructions


   Compiling
   ---------
     
     You need to have the Java Servlet API (JSDK) 2.0 in your CLASSPATH to 
     compile Java Apache SSI. Please get this from: 
     <http://java.sun.com/products/servlet/>

     To compile the source code, go to the src/java directory and
     type:

     $ make
	
     you'll get JavaApacheSSI.jar
     
     If you grabbed the distribution, the JavaApacheSSI.jar is already 
     compiled for you.

  Installing
  ----------

       Apache JServ
       ------------
       In order to include the Java Apache SSI classes in your servlet 
       engine, you have to enable the server side inclusion by mapping the 
       ".jhtml" URI to the "org.apache.servlet.ssi.SSI" servlet by doing 
       the following:

       In your Apache config file add:
         ApJServAction .jhtml /servlets/org.apache.servlet.ssi.SSI

       Change the /servlets/ part to be the location of your zone.

       In your zone.properties file add:
         wrapper.classpath=/path/to/JavaApacheSSI.jar

       Change the /path/to/ part to be the path to the location of your 
       JavaApacheSSI.jar file.

       If you would like to use the URL-Rewriting feature, use the
       org.apache.servlet.ssi.ParameterPropagatingSSI - Servlet instead.
       Consult the HTML-documentation for further information.

       Other Servlet Engines
       ---------------------
       Java Apache SSI will work with other servlet engines that meet the 
       requirements defined above. Please see the Apache JServ installation 
       instructions for hints on how to configure your servlet engine in 
       order to do suffix/action mapping.
 
       Servlet Parameters
       ------------------
       The SSI Servlet understands some optional parameters which can 
       be given in the init Arguments:

       o SSISiteRoot (path)
         In order to use traditional SSI directives (&lt;!--#..),
         pass the following init argument to the "org.apache.servlet.ssi.SSI" 
         servlet (by following your servlet engine instructions):

            SSISiteRoot=/site/root

         Replace /site/root by the top level directory of your site.
         This is the DocumentRoot in your Apache 
         configuration file.

         Beware, the SSI directives are not (yet) fully implemented.

       o expires     (integer)
         SSI documents usually contain dynamic content and thus shouldn't
         be cached by clients. With the 'expire' parameter you
         can give the number of seconds after the generated document
         should be considered stale. Use negative values to prevent
         caching (expiration in the past).
         This sets the 'Expires' header (RFC2068, 14.21).

       o PropagateParameters (';'-seperated stringlist)
         - ParameterPropagatingSSI only - 
	 Semicolon seperated list of parameters to be propagated.
	 See HTML document describing this servlet.


       With Apache JServ, you just have to insert a line in your
       zone.properties file go apply these parameters:

       servlet.org.apache.servlet.ssi.SSI.initArgs=SSISiteRoot=/site/root, \
						   expires=-1000
  
                                           The Java Apache Project
                                           <http://java.apache.org/>
@


1.1.2.2
log
@o new Parameter 'compresslarge'
   If the output becomes larger than the given number
   of bytes, it is compressed. The size of the output is a heuristic value
   based on the size of the last generated pagesizes. It is a weighted
   mean value: 1/2*(size of lastpage) + 1/8*(size of the page before) + 1/4*...
   First call of the page will not be compressed.

   Output is only compressed if the browser supplies the
   Accept-Encoding Header. Supported compress algorithms are
   gzip and compress.

   This evaluates the Accept-Encoding header and
   sets the Content-Encoding and
   Vary headers (RFC2068, 14.3, 14.12, 14.43).
@
text
@a82 16
       o compresslarge  (size in Bytes)
         - experimental -
         If the output becomes larger than the given number
         of bytes, it is compressed. The size of the output is a heuristic value
         based on the size of the last generated pagesizes. It is a weighted
         mean value: 1/2*(size of lastpage) + 1/8*(size of the page before) + 1/4*...
         First call of the page will not be compressed.

         Output is only compressed if the browser supplies the
         Accept-Encoding Header. Supported compress algorithms are
         gzip and compress.

         This evaluates the Accept-Encoding header and
         sets the Content-Encoding and
         Vary headers (RFC2068, 14.3, 14.12, 14.43).

@


1.1.2.3
log
@o documentation updates; direct links to the sections of the
  RFC's mentioned.
@
text
@d77 1
a77 1
         be cached by clients. With the 'expires' parameter you
d86 3
a88 5
         of bytes, it is compressed. 
	 The size of the output which decides whether deflation
	 is used or not is a heuristic value based on the size of the 
	 last generated pagesizes. It is a weighted mean value:	  
	 1/2*(size of lastpage) + 1/8*(size of the page before) + 1/4*...
a93 6
	 NOTE that compression uses CPU cycles and takes a bit of
	 time. So using this option may not make much sense for the
	 intranet but may be useful for pages larger than
	 several 10s kBs served to the internet.
	 See the output of your access_log for result: typical
	 pages become 5-10 times smaller with compression.
@


1.1.2.4
log
@o make buffering an option
@
text
@a6 1
                   -- see docs/install.html as well --
a106 18
       o buffered  ("yes"|"no")
         Buffer the Output of the SSI servlet. This is needed if you 
	 want to set headers within in the included servlets which 
	 should affect the whole output. Use this if you need to set 
	 headers (i.e. cookies, esp. if you want to use cookie based 
	 session handling; see documentation of your servlet engine). 
	 Another feature is, that output is a bit faster than without 
	 buffering if you have many 'active' places in the Page, 
	 e.g. doing URL rewriting with the ParameterPropagatingSSI.

	 Drawbacks are, that this uses a bit more memory (the whole page 
	 output is buffered) which in turn is work for the garbage 
	 collector. And you've to wait until the whole page is created 
	 which may make you feel that it's indeed slower ..

	 Since the buffered output allows to determine the pagesize, this
	 options sets the Content-Length header (RFC2068, 14.14).

a115 1
       Example:
@


