2011/08/05 - Jakarta Cactus has been retired.

For more information, please explore the Attic.

View Javadoc

1   /* 
2    * ========================================================================
3    * 
4    * Licensed to the Apache Software Foundation (ASF) under one or more
5    * contributor license agreements.  See the NOTICE file distributed with
6    * this work for additional information regarding copyright ownership.
7    * The ASF licenses this file to You under the Apache License, Version 2.0
8    * (the "License"); you may not use this file except in compliance with
9    * the License.  You may obtain a copy of the License at
10   * 
11   *   http://www.apache.org/licenses/LICENSE-2.0
12   * 
13   * Unless required by applicable law or agreed to in writing, software
14   * distributed under the License is distributed on an "AS IS" BASIS,
15   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   * See the License for the specific language governing permissions and
17   * limitations under the License.
18   * 
19   * ========================================================================
20   */
21  package org.apache.cactus.spi.client.connector;
22  
23  import junit.framework.Test;
24  
25  import org.apache.cactus.Request;
26  import org.apache.cactus.spi.client.ResponseObjectFactory;
27  
28  /**
29   * Any communication protocol (e.g HTTP) used to connect between
30   * Cactus client side and Cactus server side must implement this lifecycle 
31   * interface. This interface is part of the connector SPI.
32   * 
33   * Here is the lifecycle followed by Cactus core:
34   * <ul>
35   *   <li>
36   *     Call {@link #createRequest} to create a request object that will be
37   *     passed to the <code>begin()</code> and <code>beginXXX()</code> 
38   *     methods. They will in turn enrich it with values set by the user.
39   *   </li>
40   *   <li>
41   *     Call <code>begin()</code> and <code>beginXXX()</code> methods.
42   *   </li>
43   *   <li>
44   *     Call {@link #runTest} to execute the tests.
45   *   </li>
46   *   <li>
47   *     Call {@link #createResponseObjectFactory} to create a factory that is 
48   *     used to create a test response object that will be passed to the 
49   *     <code>endXXX()</code> and <code>end()</code> methods.
50   *   </li>
51   *   <li>
52   *     Call <code>endXXX()</code> and <code>end()</code> methods.
53   *   </li>
54   *   <li>
55   *     Call {@link #afterTest} to let the connector implementor clean up after
56   *     the test. For example, the HTTP connector implementation closes the HTTP
57   *     connection if the user has not closed it himself.
58   *   </li>
59   * </ul> 
60   * 
61   * @version $Id: ProtocolHandler.java 238991 2004-05-22 11:34:50Z vmassol $
62   * @since 1.6 
63   */
64  public interface ProtocolHandler
65  {
66      /**
67       * Create a request object that will be passed to the <code>begin()</code>
68       * and <code>beginXXX()</code> methods. They will in turn enrich it with 
69       * values set by the user.
70       * 
71       * @return the request object
72       */
73      Request createRequest();
74      
75      /**
76       * Connect to the server side (to the redirector proxy), passing all 
77       * information to execute the test there, trigger the test execution and
78       * gather the test results.
79       *
80       * @param theDelegatedTest the Cactus test to execute
81       * @param theWrappedTest optionally specify a pure JUnit test case that is
82       *        being wrapped and will be executed on the server side
83       * @param theRequest the request containing data to connect to the 
84       *        redirector proxy
85       * @return an object holding state information that should be preserved and
86       *         that will be passed to {@link #createResponseObjectFactory} and
87       *         {@link #afterTest} later on 
88       * @exception Throwable any error that occurred when connecting to the 
89       *            server side, when executing the test or when gathering the
90       *            test result.
91       */
92      ProtocolState runTest(Test theDelegatedTest, Test theWrappedTest,
93          Request theRequest) throws Throwable;
94  
95      /**
96       * Create a factory that is used by the core to create test response object 
97       * that will be passed to the <code>endXXX()</code> and <code>end()</code> 
98       * methods.
99       * 
100      * @param theState any state information that has been preserved from the
101      *        {@link #runTest} method (e.g. the HTTP connection object)  
102      * @return the response object factory
103      */
104     ResponseObjectFactory createResponseObjectFactory(ProtocolState theState);
105 
106     /**
107      * Let the connector implementor clean up after the test. For example, the 
108      * HTTP connector implementation closes the HTTP connection if the user has 
109      * not closed it himself.
110      *  
111      * @param theState any state information that has been preserved from the
112      *        {@link #runTest} method (e.g. the HTTP connection object)  
113      * @throws Exception on error 
114      */
115     void afterTest(ProtocolState theState) throws Exception;
116 }