<?xml version="1.0"?>

<!--
 * ========================================================================
 * 
 * Copyright 2001-2004 The Apache Software Foundation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * 
 * ========================================================================
-->

<document id="howto_ejb">

  <properties>
    <title>EJB Testing with Cactus Howto</title>
  </properties>

  <body>

  <section title="Introduction">

    <p>
      This document explains how to unit test EJBs with Cactus. It is
      divided in 2 parts:
    </p>
    <ul>
      <li>
        <jump anchor="ejb_general">General concepts</jump>: explains the
        generic concepts behind EJB unit testing with Cactus,
      </li>
      <li>
        <jump anchor="ejb_j2eeri">J2EE RI tutorial</jump>: provides a
        detailed tutorial, on a sample, on how to explicitely perform EJB
        unit testing with the
        <link href="http://java.sun.com/j2ee/download.html#sdk">J2EE Reference
        Implementation</link> server from Sun.
      </li>
    </ul>

    <note>
      EJB unit testing works with Cactus 1.0 or later.
    </note>

  </section>

  <anchor id="ejb_general"/>
  <section title="General Concepts">

    <section title="Why use Cactus for testing EJBs?">

      <p>
        You might be wondering why you would use Cactus to unit test your
        EJBs whereas you could use standard JUnit test cases. Indeed,
        you could write a standard JUnit test case and view your code as
        client side code for the EJB to test ... There are actually a few
        reasons to choose Cactus instead:
      </p>
      <ul>
        <li>
          If you are using local interfaces (EJB 2.0), then your beans cannot be called remotely
          (i.e. the caller need to be in the same jvm). However, as all Cactus redirectors run on
          the server side, you can unit test your local interfaces with Cactus.
        </li>
        <li>
          Very often the production code that will call the EJBs is server
          side code (Servlets, JSPs, Tag libs or Filters). This means that if
          you run the tests from a standard JUnit test case, your tests will
          run in a different execution environment than the production one,
          which can lead to different test results,
        </li>
        <li>
          An application using EJBs very often includes a front end part which
          is in almost all cases a web application (i.e. using Servlets,
          JSP, Tag libs or Filters). It means that you would also need a
          framework for unit testing these components. Cactus is providing
          a comprehensive and consistent framework for testing all server
          side components. This is a compelling enough reason to use it !
        </li>
        <li>
          Cactus provides automated Ant tasks to automatically start your
          EJB server, run the tests and stop it, thus automating your
          entire test process and making it easy to implement continuous
          build and continuous integration of your J2EE project.
        </li>
      </ul>

    </section>

    <section title="The process">

      <p>
        You can unit test your EJBs from any of Cactus redirectors:
        <code>ServletTestCase</code>, <code>JspTestCase</code> or
        <code>FilterTestCase</code>.
      </p>
      <p>
        This means that you would write a test case class that extends any
        of Cactus redirectors, get a home reference to your EJB, create an
        instance of it, call the method to test and perform asserts on the
        result.
      </p>
      <p>
        It is that simple ! What is slightly more complex is the deployment
        of your EJBs to your EJB container but you should be familiar with
        this, right?
      </p>

    </section>

  </section>

  <anchor id="ejb_j2eeri"/>
  <section title="J2EE RI Tutorial">

    <p>
      This <link href="site:howto_ejb_j2eeri">J2EE RI tutorial</link>
      is a step by step guide for writing Cactus EJB unit test for the
      Sun J2EE RI server.
    </p>

  </section>

  </body>
</document>
