Configuration Howto

Last update : April 21 2002
Doc for : v1.3

About
  • What is Cactus ?
  • News
  • Changes
  • Features/Status
  • Goals
  • Roadmap/Todo
  • Contributors
  • Contributing
  • Cactus Users
  • Tested on ...
  • License


  • Downloads
  • Downloads


  • Documentation
  • How it works ?
  • Getting Started
  • Mock vs Container
  • Javadocs
  • FAQ


  • Howto Guides
  • Classpath Howto
  • Config Howto
  • Migration Howto
  • TestCase Howto
  • Security Howto
  • Ant Howto
  • HttpUnit Howto
  • Sample Howto
  • EJB Howto
  • IDE Howto
  • JUnitEE Howto


  • Support
  • Bug database
  • Mailing list


  • Misc.
  • Why the name ?
  • Logo Challenge
  • Resources
  • Stats


  • Developers
  • CVS
  • Coding Conventions
  • Build results


  • 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

    The cactus.properties file contains several configuration properties for Cactus.

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

    Property Name   cactus.contextURL  
    Description   Webapp Context under which the application to test runs.  
    Example   cactus.contextURL = http://localhost:8080/test  


    Property Name   cactus.servletRedirectorName  
    Description   Name of the Cactus Servlet Redirector as it is mapped on the server side in web.xml (see below). This property is needed only if your test classes are extending ServletTestCase (see the TestCase Howto tutorial).  
    Example   cactus.servletRedirectorName = ServletRedirector  


    Property Name   cactus.jspRedirectorName  
    Description   Name of the Cactus JSP Redirector as it is mapped on the server side in web.xml (see below). This property is needed only if your test classes are extending JspTestCase (see the TestCase Howto tutorial).  
    Example   cactus.jspRedirectorName = JspRedirector  


    Property Name   cactus.filterRedirectorName (For J2EE API 1.3 only)  
    Description   Name of the Cactus Filter Redirector as it is mapped on the server side in web.xml (see below). This property is needed only if your test classes are extending FilterTestCase (see the TestCase Howto tutorial).  
    Example   cactus.filterRedirectorName = FilterRedirector  


    Property Name   cactus.enableLogging  
    Description   If set to "true" Cactus internal logging is enabled. Note that you will also need log4j.jar in your classpath to activate logging. If not specified or set to a value different than "true", Cactus logging is disabled.  
    Example   cactus.enableLogging = true  

    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.
    # You need to specify in these URLs the webapp context that you use for your
    # application. In the example below, the context is "test".
    
    # Web app Context under which our application to test runs
    cactus.contextURL = http://localhost:@test.port@/test
    
    # Default Servlet Redirector Name. Used by ServletTestCase test cases.
    cactus.servletRedirectorName = ServletRedirector
    
    # Default JSP Redirector Name. Used by JspTestCase test cases.
    cactus.jspRedirectorName = JspRedirector
    
    # Default Filter Redirector Name. Used by FilterTestCase test cases.
    cactus.filterRedirectorName = FilterRedirector
    
    # Enable Cactus internal logging
    #cactus.enableLogging = true
    

    There are 2 ways to tell Cactus where cactus.properties is located.

    • The preferred mechanism is to put it in the client side classpath (i.e. have a CLASSPATH entry that points to the directory where it is located).
    • The other option is to pass a command line parameter when starting your JVM. See the Command line section below.

    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. In addition you need to explicitely tell Cactus to perform logging (if that's what you want). This can be achieved in 2 ways :

    • By having a cactus.enableLogging = true property in your cactus.properties file (as described above),
    • By passing a property on the Java command line when starting the JVM. See the Command line section.

    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 = %d{ABSOLUTE} [%t] %-5p %-30.30c{2} %x - %m %n
    
    # Any application log which uses Log4J will be logged to the Cactus log file
    log4j.rootCategory=DEBUG, cactus
    
    # By default we don't log at the DEBUG level for Cactus log, in order not to generate too
    # many logs. However, should a problem arise and logs need to be sent to the Cactus dev team,
    # then we will ask you to change this to DEBUG.
    log4j.category.org.apache.cactus = WARN, cactus
    log4j.additivity.org.apache.cactus=false
    

    If you want to understand how to configure Log4j, go to the Log4j web site.

    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.


    Command line parameters

    Note Command line parameters are purely optional and should only be used for very specific cases where the preferred method cannot be used (the preffered method is through cactus.properties).

    The following command line properties can be passed on the java command line :

    Property Name   cactus.enableLogging  
    Description   If set to "true" Cactus internal logging is enabled. Note that you will also need log4j.jar in your classpath to activate logging. If not specified or set to a value different than "true", Cactus logging is disabled.  
    Example   -Dcactus.enableLogging=true  


    Property Name   cactus.config  
    Description   Specify where to find the Cactus configuration file. By default Cactus looks for a cactus.properties file in the classpath. This property overrides this behaviour.  
    Example   -Dcactus.config=conf/mycactus.properties  


    Server side configuration files

    cactus.properties

    First and foremost, this file is completely optional on the server side (whereas it is mandatory on the client side). It is only used to turn on Cactus internal logging on the server side.

    Note Please note that Cactus logging on the server side can also be turned on by using a java command line property (see the command line section below).

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

    Property Name   cactus.enableLogging  
    Description   If set to "true" Cactus internal logging is enabled. Note that you will also need log4j.jar in your classpath to activate logging. If not specified or set to a value different than "true", Cactus logging is disabled.  
    Example   cactus.enableLogging = true  

    Location of cactus.properties works in the same way as on the client side.


    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.3//EN"
        "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">
    
    <web-app>
    
        <filter>
            <filter-name>FilterRedirector</filter-name>
            <filter-class>org.apache.cactus.server.FilterTestRedirector</filter-class>
        </filter>
    
        <filter-mapping>
            <filter-name>FilterRedirector</filter-name>
            <url-pattern>/FilterRedirector</url-pattern>
        </filter-mapping>
    
        <servlet>
            <servlet-name>ServletRedirector</servlet-name>
            <servlet-class>org.apache.cactus.server.ServletTestRedirector</servlet-class>
        </servlet>
    
        <servlet>
            <servlet-name>JspRedirector</servlet-name>
            <jsp-file>/jspRedirector.jsp</jsp-file>
        </servlet>
    
        <servlet-mapping>
            <servlet-name>ServletRedirector</servlet-name>
            <url-pattern>/ServletRedirector</url-pattern>
        </servlet-mapping>
    
        <servlet-mapping>
            <servlet-name>JspRedirector</servlet-name>
            <url-pattern>/JspRedirector</url-pattern>
        </servlet-mapping>
    
    </web-app>
    

    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 directory where you unpacked your Cactus distribution) in a directory in your webapp and you need to put it's relative path in the mapping defined above (here we have put it in the webapp root.

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

    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.

    Lastly, if you need to unit test code that uses the Servlet Security API, please check the Security Howto.


    log_server.properties

    It works in the same way as for the client side.

    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 = %d{ABSOLUTE} [%t] %-5p %-30.30c{2} %x - %m %n
    
    # Any application log which uses Log4J will be logged to the Cactus log file
    log4j.rootCategory=DEBUG, cactus
    
    # By default we don't log at the DEBUG level for Cactus log, in order not to generate too
    # many logs. However, should a problem arise and logs need to be sent to the Cactus dev team,
    # then we will ask you to change this to DEBUG.
    log4j.category.org.apache.cactus = WARN, cactus
    log4j.additivity.org.apache.cactus=false
    

    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 !


    Command line parameters

    Command line parameters on the server side are exactly the same as on the client side. in order to use them you'll have to modify the startup script of your container and add your properties to it.

    Again, please bear in mind that this is completely optional and that the preferred method is by using cactus.properties.






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