1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 */
18
19 package org.apache.jmeter.protocol.java.sampler;
20
21 import org.apache.jmeter.config.Arguments;
22 import org.apache.jmeter.samplers.SampleResult;
23
24 /**
25 * This interface defines the interactions between the JavaSampler and external
26 * Java programs which can be executed by JMeter. Any Java class which wants to
27 * be executed as a JMeter test must implement this interface (either directly
28 * or indirectly through AbstractJavaSamplerClient).
29 * <p>
30 * JMeter will create one instance of a JavaSamplerClient implementation for
31 * each user/thread in the test. Additional instances may be created for
32 * internal use by JMeter (for example, to find out what parameters are
33 * supported by the client).
34 * <p>
35 * When the test is started, setupTest() will be called on each thread's
36 * JavaSamplerClient instance to initialize the client. Then runTest() will be
37 * called for each iteration of the test. Finally, teardownTest() will be called
38 * to allow the client to do any necessary clean-up.
39 * <p>
40 * The JMeter JavaSampler GUI allows a list of parameters to be defined for the
41 * test. These are passed to the various test methods through the
42 * {@link JavaSamplerContext}. A list of default parameters can be defined
43 * through the getDefaultParameters() method. These parameters and any default
44 * values associated with them will be shown in the GUI. Users can add other
45 * parameters as well.
46 * <p>
47 * When possible, Java tests should extend {@link AbstractJavaSamplerClient
48 * AbstractJavaSamplerClient} rather than implementing JavaSamplerClient
49 * directly. This should protect your tests from future changes to the
50 * interface. While it may be necessary to make changes to the JavaSamplerClient
51 * interface from time to time (therefore requiring changes to any
52 * implementations of this interface), we intend to make this abstract class
53 * provide reasonable default implementations of any new methods so that
54 * subclasses do not necessarily need to be updated for new versions.
55 * Implementing JavaSamplerClient directly will continue to be supported for
56 * cases where extending this class is not possible (for example, when the
57 * client class is already a subclass of some other class).
58 * <p>
59 * See {@link org.apache.jmeter.protocol.java.test.SleepTest} for an example of
60 * how to implement this interface.
61 *
62 * @version $Revision: 674365 $
63 */
64 public interface JavaSamplerClient {
65 /**
66 * Do any initialization required by this client. It is generally
67 * recommended to do any initialization such as getting parameter values in
68 * the setupTest method rather than the runTest method in order to add as
69 * little overhead as possible to the test.
70 *
71 * @param context
72 * the context to run with. This provides access to
73 * initialization parameters.
74 */
75 void setupTest(JavaSamplerContext context);
76
77 /**
78 * Perform a single sample for each iteration. This method returns a
79 * <code>SampleResult</code> object. <code>SampleResult</code> has many
80 * fields which can be used. At a minimum, the test should use
81 * <code>SampleResult.sampleStart</code> and
82 * <code>SampleResult.sampleEnd</code>to set the time that the test
83 * required to execute. It is also a good idea to set the sampleLabel and
84 * the successful flag.
85 *
86 * @see org.apache.jmeter.samplers.SampleResult#sampleStart()
87 * @see org.apache.jmeter.samplers.SampleResult#sampleEnd()
88 * @see org.apache.jmeter.samplers.SampleResult#setSuccessful(boolean)
89 * @see org.apache.jmeter.samplers.SampleResult#setSampleLabel(String)
90 *
91 * @param context
92 * the context to run with. This provides access to
93 * initialization parameters.
94 *
95 * @return a SampleResult giving the results of this sample.
96 */
97 SampleResult runTest(JavaSamplerContext context);
98
99 /**
100 * Do any clean-up required by this test at the end of a test run.
101 *
102 * @param context
103 * the context to run with. This provides access to
104 * initialization parameters.
105 */
106 void teardownTest(JavaSamplerContext context);
107
108 /**
109 * Provide a list of parameters which this test supports. Any parameter
110 * names and associated values returned by this method will appear in the
111 * GUI by default so the user doesn't have to remember the exact names. The
112 * user can add other parameters which are not listed here. If this method
113 * returns null then no parameters will be listed. If the value for some
114 * parameter is null then that parameter will be listed in the GUI with an
115 * empty value.
116 *
117 * @return a specification of the parameters used by this test which should
118 * be listed in the GUI, or null if no parameters should be listed.
119 */
120 Arguments getDefaultParameters();
121 }