Save This Page
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 }