Configuration Howto

Last update : September 25 2001

About
  • What is Cactus ?
  • Features/Status
  • Goals
  • News/Changes
  • Roadmap/Todo
  • Contributors
  • Contributing
  • License
  • Feedback


  • Downloads
  • Downloads


  • Documentation
  • How it works ?
  • Getting Started
  • Mock vs Container
  • API Reference


  • Howto Guides
  • Config Howto
  • TestCase Howto
  • Ant Howto
  • HttpUnit Howto
  • Sample Howto
  • EJB Howto
  • IDE Howto


  • Support
  • Bug database
  • Mailing list
  • FAQ


  • Misc.
  • Why the name ?
  • Resources


  • Developers
  • CVS
  • Coding Conventions


  • The configuration files

    Note You should read the Getting Started guide first.

    Here are the configuration files used by Cactus :

    Configuration files

    There are two kind of configuration files :

    Client side configuration files

    cactus.properties

    Note Do not forget to put this file on the client classpath (meaning you need to put the directory where this file is located in the client side classpath, not the file itself !). See the Getting Started guide to understand how to set up the classpath.

    The cactus.properties file contains several configuration properties. At the current time it is only used to tell the client side part of Cactus what is the URL to connect to the different Cactus Redirectors set up on the server side (see How it works if you don't know what a Cactus Redirector is).

    Here are the properties that you can set in cactus.properties :

    Property Name   cactus.servletRedirectorURL  
    Description   URL to which the Servlet Redirector is mapped to. This is needed only if your test classes are extending ServletTestCase (see the TestCase Howto tutorial).  
    Example   http://localhost:8080/test/ServletRedirector/  


    Property Name   cactus.jspRedirectorURL  
    Description   URL to which the JSP Redirector is mapped to. This is needed only if your test classes are extending JspTestCase (see the TestCase Howto tutorial).  
    Example   http://localhost:8080/test/JspRedirector/  


    Property Name   cactus.filterRedirectorURL  
    Description   URL to which the Filter Redirector is mapped to. This is needed only if your test classes are extending FilterTestCase (see the TestCase Howto tutorial). Cactus 1.2 only.  
    Example   http://localhost:8080/test/FilterRedirector/  

    Sample cactus.properties file :

    # Configuration file for Cactus.
    
    # Each project using Cactus need to have such a file put in the client side
    # CLASSPATH (Meaning the directory containgin this file should be in the client
    # side CLASSPATH, not the file itself of course ... :) )
    
    # Defines the URLs that will be used by Cactus to call it's redirectors
    # (Servlet and JSP). You need to specify in these URLs the webapp context
    # that you use for your application. In the example below, the context is
    # "test".
    
    cactus.servletRedirectorURL = http://localhost:8080/test/ServletRedirector/
    cactus.jspRedirectorURL = http://localhost:8080/test/JspRedirector/
    cactus.filterRedirectorURL = http://localhost:8080/test/FilterRedirector/
    

    Note Notice the trailing slash ("/") to Redirector URLs. This is because Cactus uses the JDK HttpURLConnection class to connect to these URLs and if your code on the server side returns an HTTP status code greater than 400, HttpURLConnection will return an exception. It does not if the URL ends with a forward slash ("/") !


    log_client.properties

    A default log_client.properties is already provided in the cactus.jar jar. It is used for configuring Log4j, which is the logging framework used by Cactus to log debug information.

    If the Log4j jar is not present on the client side classpath, Cactus will not log anything. To enable logging, just put the Log4j jar in the client side classpath.

    The default log_client.properties is :

    # Properties for configuring Log4j
    # This is the configuring for logging on the JUnit side (i.e. the client side)
    
    log4j.appender.cactus = org.apache.log4j.FileAppender
    log4j.appender.cactus.File = cactus_client.log
    log4j.appender.cactus.Append = false
    log4j.appender.cactus.layout = org.apache.log4j.PatternLayout
    log4j.appender.cactus.layout.ConversionPattern = %r [%t] %-5p %c{2} %x - %m %n
    
    log4j.category.org.apache.cactus = DEBUG, cactus
    

    If you want to understand how to configure Log4j, go to the Log4j web site. Basically, this configuration tells Log4j to log all debug level messages to a cactus_client.log file (which will be located in the directory where you started the client JVM).

    If you wish to define another file name and location or other logging parameter, just provide your own log_client.properties file (it has to be named this way) and put in the client side classpath before the cactus.jar file.



    Server side configuration files

    web.xml

    Your server side tests are packaged as a web application (either expanded or as .war file) and thus you need to have a web.xml file to configure your test web application.

    Note If your servlet engine does not support web applications, it won't support a web.xml file. You'll need to edit your servlet engine proprietary configuration file and find out out to map a Servlet, JSP or Filter to a URL.

    You need to register the Cactus Redirectors that you use (see How it works if you don't know what a Cactus Redirector is).

    For example, in order to match the sample cactus.properties file defined above, we'll need to name our web application "test" and write our web.xml in the following way :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    
    <!DOCTYPE web-app
        PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
        "http://java.sun.com/j2ee/dtds/web-app_2.2.dtd">
    
    <web-app>
    
        <!-- Filter Redirector definition -->
        <filter>
            <filter-name>FilterRedirector</filter-name>
            <filter-class>org.apache.cactus.server.FilterTestRedirector</filter-class>
        </filter>
    
        <!-- Filter Redirector URL mapping -->
        <filter-mapping>
            <filter-name>FilterRedirector</filter-name>
            <url-pattern>/FilterRedirector/</url-pattern>
        </filter-mapping>
    
        <!-- Servlet Redirector configuration -->
        <servlet>
            <servlet-name>ServletRedirector</servlet-name>
            <servlet-class>org.apache.cactus.server.ServletTestRedirector</servlet-class>
        </servlet>
    
        <!-- JSP Redirector URL configuration -->
        <servlet>
            <servlet-name>JspRedirector</servlet-name>
            <jsp-file>/somewhere/jspRedirector.jsp</jsp-file>
        </servlet>
    
        <!-- Servlet Redirector URL mapping -->
        <servlet-mapping>
            <servlet-name>ServletRedirector</servlet-name>
            <url-pattern>/ServletRedirector/</url-pattern>
        </servlet-mapping>
    
        <!-- JSP Redirector URL mapping -->
        <servlet-mapping>
            <servlet-name>JspRedirector</servlet-name>
            <url-pattern>/JspRedirector/</url-pattern>
        </servlet-mapping>
    
    </web-app>
    

    Note Notice the trailing slash ("/") to Redirector mappings. This is because Cactus uses the JDK HttpURLConnection class to connect to these URLs and if your code on the server side returns an HTTP status code greater than 400, HttpURLConnection will return an exception. It does not if the URL ends with a forward slash ("/") !

    Note If you are using the JSP Redirector (i.e. you have test classes that extend JspTestCase), you must copy the jspRedirector.jsp file (found in the sample/web/test directory where you unpacked your Cactus distribution) anywhere in your webapp and you need to out it's relative path in the mapping defined above (here we have put it in a directory named somewhere right under the webapp root.

    Note We have used the <jsp-file> tag to define the mapping for the JSP Redirector page. However some servlet engine still don't support this tag (although it is in the Servlet 2.2 specifications). If this is your case, simply do not define any mapping in web.xml for the JSP Redirector and use the following URL in your cactus.properties : cactus.jspRedirectorURL = http://localhost:8080/test/somewhere/jspRedirector.jsp

    If you want to provide some initialisation parameters that will be available to the config implicit object available to you in your test case, simply use the standard <init-param> tag.

    For example, for the Servlet Redirector (same principle applies to all other redirectors) :

    [...]
        <servlet>
            <servlet-name>ServletRedirector</servlet-name>
            <servlet-class>org.apache.cactus.server.ServletTestRedirector</servlet-class>
            <init-param>
              <param-name>param1</param-name>
              <param-value>value1 used for testing</param-value>
            </init-param>
        </servlet>
    [...]
    

    Note Within your testXXX() code, you can also call the config.setInitParameter() method (config being the implicit object of type ServletConfig) to simulate initialisation parameters as if they had been defined in your web.xml.


    log_server.properties

    A default log_server.properties is already provided in the cactus.jar jar. It is used for configuring Log4j, which is the logging framework used by Cactus to log debug information.

    If the Log4j jar is not present on the server side classpath, Cactus will not log anything. To enable logging, just put the Log4j jar in the server side classpath.

    The default log_server.properties is :

    # Properties for configuring Log4j
    # This is the configuring for logging on the server side
    
    log4j.appender.cactus = org.apache.log4j.FileAppender
    log4j.appender.cactus.File = cactus_server.log
    log4j.appender.cactus.Append = false
    log4j.appender.cactus.layout = org.apache.log4j.PatternLayout
    log4j.appender.cactus.layout.ConversionPattern = %r [%t] %-5p %c{2} %x - %m %n
    
    log4j.category.org.apache.cactus = DEBUG, cactus
    

    If you want to understand how to configure Log4j, go to the Log4j web site. Basically, this configuration tells Log4j to log all debug level messages to a cactus_server.log file (which will be located in the current directory of your servlet engine).

    If you wish to define another file name and location or other logging parameter, just provide your own log_server.properties file (it has to be named this way) and put in the WEB-INF/classes directory of your webapp (and hope that the webapp classloader of your server picks up the files in WEB-INF/classes before the ones in WEB-INF/lib, where cactus.jar is located ... :) I don't know if this is part of the specification). Alternatively, edit the file in cactus.jar !






    Copyright © 2000-2001 The Apache Software Foundation. All Rights Reserved.