
		         A P A C H E   J S S I
                             Version 1.1.2


  What is it?
  -----------
  
  Apache JSSI is Java servlet that provides support for including dynamic
  servlet output from within HTML documents via the <SERVLET> tag as specified
  by the JavaSoft Java Web Server. 

  Additionally there are some extensions which can make your life easier:
    o Support of some traditional SSI-commands (like <!--#ECHO ...-->)
    o URL-Rewriting of any <A HREF=..> in the page
      to allow session tracking without cookies. See HTML-doc.
    o For Developers: An easy way to extend the SSI Servlet to handle 
      any tag (consult the JavaDoc for TagHandlers)


  The Latest Version
  ------------------

  Details of the latest version can be found on the Java Apache 
  Project web site <http://java.apache.org>.

  Changes to 1.0
  ---------------
  Note that the servlet has been renamed from
  Apache JServSSI to Apache JSSI since it became a project not dependant
  on the JServ project. 
  
  The package name changed from org.apache.jservssi to org.apache.servlet.ssi.

  Several bugs have been fixed, it parses faster, uses less memory and has
  a bunch of (nonstandard) extensions.

  Licensing
  ---------

  Please see the file called LICENSE.
  
  Requirements
  ------------
  
    o  Any servlet engine compatible with the 2.0 Servlet API specification
       (the use of Apache JServ is highly recommended). Note that the
       JSDK 2.1 isn't supported yet and the SSI servlet may or may not
       work with JSDK 2.1 compliant servlet engines.
       
    o  Any Java 1.1 compatible compiler
    
  Installation
  ------------
  Please see the file called INSTALL

  Usage
  -----
  
  Servlet output may be included in an HTML document by use of the <SERVLET>
  tag. For example, to embed the output of the HelloWorldServlet servlet in 
  an HTML page, you might write the following:
  
        ... (some HTML code) ...
        <SERVLET CODE="HelloWorldServlet.class">
        Your web server has not been configured to support servlet tags.
        </SERVLET>
        ... (more HTML code) ...

  When this page is served from the web server, the code above will be replaced
  with the output of HelloWorldServlet. If you see the message between the tags 
  instead, there is a problem with your server configuration. If this happens, 
  check to make sure your file has a ".jhtml" extension and that the server is 
  properly configured.
       
  Two attributes are used by the <SERVLET> tag, and they are roughly 
  equivalent: 

   o The CODE attribute may be set to the name of a class file (the ".class" 
     extension is optional) containing the servlet to be run. This servlet must
     be visible by the Apache JSSI servlet. 
   o The NAME attribute may also be set to the name of the servlet to be run 
     (with no class extension). 

  In some implementations of <SERVLET> tags, if both NAME and CODE attributes
  are set, the servlet designated by CODE will then become available for future
  use under the symbolic named designated by the NAME attribute. This is not
  currently supported. 

  Note that both the <SERVLET> and </SERVLET> tags must be present.       
       
  You may send parameters to a servlet via the PARAM tag, which should be 
  placed between the <SERVLET> and </SERVLET> tags, like so:  

        <SERVLET CODE="MyServlet.class">
         <PARAM NAME="param1" VALUE="valueOfParam1">
         <PARAM NAME="anotherParam" VALUE="valueOfAnotherParam">
        </SERVLET>

  You could then access these parameters from your servlet as follows:  

        public void doGet(HttpServletRequest req, HttpServletResponse res)
        throws ServletException, IOException {
            String param1 = req.getParameter("param1");
            String anotherParam = req.getParameter("anotherParam");
        }

  For use of the URL rewriting and traditional SSI features see the
  HTML documentation.

  Notes
  -----

   o  Attribute values
      ----------------
      
      Attribute values, NAME and VALUE in the PARAM tag may be a single word 
      (NAME=xyz value=1) or must be enclosed in quotes if they contain 
      whitespace (NAME=xyz VALUE="This is a test").
      
   o  Case sensitivity and SGML 
      -------------------------
      
      This class does not care about case when reading SGML tags or their 
      attributes, so uppercase, or lowercase, or any combination thereof may 
      be used. The text in attribute values is not translated to upper- or 
      lowercase but is passed on intact.
      
   o  Error handling
      --------------
      
      To simplify error detection and correction, exceptions thrown by Java 
      Apache SSI or called servlets are printed, enclosed in comments 
      ("<!-- ... -->"), in the HTML output.


  Known Bugs
  ---------

  Servlets implementing the SingleThreadModel interface are known not to
  work together with the Apache JSSI. This is due to deficiencies of
  JSDK 2.0 which doesn't allow to implement a SSI servlet independent of
  the servlet engine.
  So you either have to 
     o write clean, reentrant servlets (preferred)
     o synchronize your service(), doGet(), doPost() methods (ugly)
   or 
     o write a SSI dependant on your servlet engine (or wait
       for JSDK 2.1)

  Thanks for using Apache JSSI.

                                           The Java Apache Project
                                           <http://java.apache.org/>
