001: /*
002: * ========================================================================
003: *
004: * Copyright 2003-2004 The Apache Software Foundation.
005: *
006: * Licensed under the Apache License, Version 2.0 (the "License");
007: * you may not use this file except in compliance with the License.
008: * You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing, software
013: * distributed under the License is distributed on an "AS IS" BASIS,
014: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015: * See the License for the specific language governing permissions and
016: * limitations under the License.
017: *
018: * ========================================================================
019: */
020: package org.apache.cactus.spi.client.connector;
021:
022: import junit.framework.Test;
023:
024: import org.apache.cactus.Request;
025: import org.apache.cactus.spi.client.ResponseObjectFactory;
026:
027: /**
028: * Any communication protocol (e.g HTTP) used to connect between
029: * Cactus client side and Cactus server side must implement this lifecycle
030: * interface. This interface is part of the connector SPI.
031: *
032: * Here is the lifecycle followed by Cactus core:
033: * <ul>
034: * <li>
035: * Call {@link #createRequest} to create a request object that will be
036: * passed to the <code>begin()</code> and <code>beginXXX()</code>
037: * methods. They will in turn enrich it with values set by the user.
038: * </li>
039: * <li>
040: * Call <code>begin()</code> and <code>beginXXX()</code> methods.
041: * </li>
042: * <li>
043: * Call {@link #runTest} to execute the tests.
044: * </li>
045: * <li>
046: * Call {@link #createResponseObjectFactory} to create a factory that is
047: * used to create a test response object that will be passed to the
048: * <code>endXXX()</code> and <code>end()</code> methods.
049: * </li>
050: * <li>
051: * Call <code>endXXX()</code> and <code>end()</code> methods.
052: * </li>
053: * <li>
054: * Call {@link #afterTest} to let the connector implementor clean up after
055: * the test. For example, the HTTP connector implementation closes the HTTP
056: * connection if the user has not closed it himself.
057: * </li>
058: * </ul>
059: *
060: * @version $Id: ProtocolHandler.java 238991 2004-05-22 11:34:50Z vmassol $
061: * @since 1.6
062: */
063: public interface ProtocolHandler {
064: /**
065: * Create a request object that will be passed to the <code>begin()</code>
066: * and <code>beginXXX()</code> methods. They will in turn enrich it with
067: * values set by the user.
068: *
069: * @return the request object
070: */
071: Request createRequest();
072:
073: /**
074: * Connect to the server side (to the redirector proxy), passing all
075: * information to execute the test there, trigger the test execution and
076: * gather the test results.
077: *
078: * @param theDelegatedTest the Cactus test to execute
079: * @param theWrappedTest optionally specify a pure JUnit test case that is
080: * being wrapped and will be executed on the server side
081: * @param theRequest the request containing data to connect to the
082: * redirector proxy
083: * @return an object holding state information that should be preserved and
084: * that will be passed to {@link #createResponseObjectFactory} and
085: * {@link #afterTest} later on
086: * @exception Throwable any error that occurred when connecting to the
087: * server side, when executing the test or when gathering the
088: * test result.
089: */
090: ProtocolState runTest(Test theDelegatedTest, Test theWrappedTest,
091: Request theRequest) throws Throwable;
092:
093: /**
094: * Create a factory that is used by the core to create test response object
095: * that will be passed to the <code>endXXX()</code> and <code>end()</code>
096: * methods.
097: *
098: * @param theState any state information that has been preserved from the
099: * {@link #runTest} method (e.g. the HTTP connection object)
100: * @return the response object factory
101: */
102: ResponseObjectFactory createResponseObjectFactory(
103: 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;
115: }
|