KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > cactus > spi > client > connector > ProtocolHandler


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