
                      A P A C H E   J S E R V S S I
                           Version 1.0 (and up)


  What is it?
  -----------
  
  Apache JServSSI 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.

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

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


  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)
       
    o  Any Java 1.1 compatible compiler
    

  Installation
  ------------

  1. Compiling
     ---------
     
     The compile the source code, go to the src/ directory and type
     
     $ javac -d . *.java
     $ jar cf0 ApacheJServSSI.jar .
     
  2. Installing
     ----------
     
     Follow your servlet engine instructions to install the ApacheJServSSI.jar
     package in your servlet engine.
     
  3. Mapping
     -------
     
     Once the Apache JServSSI classes have been included in your servlet
     engine, you have to enable the server side inclusion by mapping the
     ".jhtml" URI to the "org.apache.jservssi.JServSSI" servlet by following
     your servlet engine instructions.


  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 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 JServSSI 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");
        }       
       

  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 Apache
      JServSSI or called servlets are printed, enclosed in comments 
      ("<!-- ... -->"), in the HTML output.

      
  Known bugs
  ----------
  
  Currently, the parameters set for the first servlet on a page will still be 
  set in the next servlet.
  
 

  Thanks for using Apache JServSSI.

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