001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: *
017: */
018:
019: package org.apache.jmeter.protocol.java.sampler;
020:
021: import org.apache.jmeter.config.Arguments;
022: import org.apache.jmeter.samplers.SampleResult;
023:
024: /**
025: * This interface defines the interactions between the JavaSampler and external
026: * Java programs which can be executed by JMeter. Any Java class which wants to
027: * be executed as a JMeter test must implement this interface (either directly
028: * or indirectly through AbstractJavaSamplerClient).
029: * <p>
030: * JMeter will create one instance of a JavaSamplerClient implementation for
031: * each user/thread in the test. Additional instances may be created for
032: * internal use by JMeter (for example, to find out what parameters are
033: * supported by the client).
034: * <p>
035: * When the test is started, setupTest() will be called on each thread's
036: * JavaSamplerClient instance to initialize the client. Then runTest() will be
037: * called for each iteration of the test. Finally, teardownTest() will be called
038: * to allow the client to do any necessary clean-up.
039: * <p>
040: * The JMeter JavaSampler GUI allows a list of parameters to be defined for the
041: * test. These are passed to the various test methods through the
042: * {@link JavaSamplerContext}. A list of default parameters can be defined
043: * through the getDefaultParameters() method. These parameters and any default
044: * values associated with them will be shown in the GUI. Users can add other
045: * parameters as well.
046: * <p>
047: * When possible, Java tests should extend {@link AbstractJavaSamplerClient
048: * AbstractJavaSamplerClient} rather than implementing JavaSamplerClient
049: * directly. This should protect your tests from future changes to the
050: * interface. While it may be necessary to make changes to the JavaSamplerClient
051: * interface from time to time (therefore requiring changes to any
052: * implementations of this interface), we intend to make this abstract class
053: * provide reasonable default implementations of any new methods so that
054: * subclasses do not necessarily need to be updated for new versions.
055: * Implementing JavaSamplerClient directly will continue to be supported for
056: * cases where extending this class is not possible (for example, when the
057: * client class is already a subclass of some other class).
058: * <p>
059: * See {@link org.apache.jmeter.protocol.java.test.SleepTest} for an example of
060: * how to implement this interface.
061: *
062: * @author Brad Kiewel
063: * @author <a href="mailto:jeremy_a@bigfoot.com">Jeremy Arnold</a>
064: * @version $Revision: 493789 $
065: */
066: public interface JavaSamplerClient {
067: /**
068: * Do any initialization required by this client. It is generally
069: * recommended to do any initialization such as getting parameter values in
070: * the setupTest method rather than the runTest method in order to add as
071: * little overhead as possible to the test.
072: *
073: * @param context
074: * the context to run with. This provides access to
075: * initialization parameters.
076: */
077: void setupTest(JavaSamplerContext context);
078:
079: /**
080: * Perform a single sample for each iteration. This method returns a
081: * <code>SampleResult</code> object. <code>SampleResult</code> has many
082: * fields which can be used. At a minimum, the test should use
083: * <code>SampleResult.sampleStart</code> and
084: * <code>SampleResult.sampleEnd</code>to set the time that the test
085: * required to execute. It is also a good idea to set the sampleLabel and
086: * the successful flag.
087: *
088: * @see org.apache.jmeter.samplers.SampleResult#sampleStart()
089: * @see org.apache.jmeter.samplers.SampleResult#sampleEnd()
090: * @see org.apache.jmeter.samplers.SampleResult#setSuccessful(boolean)
091: * @see org.apache.jmeter.samplers.SampleResult#setSampleLabel(String)
092: *
093: * @param context
094: * the context to run with. This provides access to
095: * initialization parameters.
096: *
097: * @return a SampleResult giving the results of this sample.
098: */
099: SampleResult runTest(JavaSamplerContext context);
100:
101: /**
102: * Do any clean-up required by this test at the end of a test run.
103: *
104: * @param context
105: * the context to run with. This provides access to
106: * initialization parameters.
107: */
108: void teardownTest(JavaSamplerContext context);
109:
110: /**
111: * Provide a list of parameters which this test supports. Any parameter
112: * names and associated values returned by this method will appear in the
113: * GUI by default so the user doesn't have to remember the exact names. The
114: * user can add other parameters which are not listed here. If this method
115: * returns null then no parameters will be listed. If the value for some
116: * parameter is null then that parameter will be listed in the GUI with an
117: * empty value.
118: *
119: * @return a specification of the parameters used by this test which should
120: * be listed in the GUI, or null if no parameters should be listed.
121: */
122: Arguments getDefaultParameters();
123: }
|