JMeter Extension Scenario

The purpose of this tutorial is to describe the general steps involved in a JMeter extension scenerio. The JMeter documentation describes what must be done on a microscopic level but does not provide an overall idea of the process. That is the intent of this brief article. The JMeter extension documentation should be consulted for details.

The high level procedure followed these steps.

  1. Planning
  2. Code the configuration object
  3. Code the configuration GUI object
  4. Code the controller object
  5. Code the controller GUI object
  6. Code the Sampler object
  7. Install your extension
  8. Tips

Planning

I've found planning a JMeter extension to involve three aspects:

  1. What you want the sampler to do
  2. What information is needed for the sampler to work
  3. How the information is to be acquired from the user

You'll notice that the coding steps are somewhat backwards from the planning steps (the sampler is coded last). The coding order was determined by which classes could be tested earliest. The config/gui can be tested in isolation. The controller can be tested with the config element. Neither of these requires a Sampler to be present initially.

Configuration Object

The role of the configuration object is to supply parameters to the Sampler that can vary from sample to sample. In the case of the UrlConfig object, this would be information such as the host name, port, GET or PUT and various parameters.

The configuration object usually inherits from org.apache.jmeter.config.AbstractConfigElement. It implements many of the methods of org.apache.jmeter.gui.JMeterComponentModel that are needed to effectively interact with JMeter.

  1. Constructor - In the constructor you should at least define the name of your configuration element. This is best delegated to the base class's setName method.

  2. Property Name Strings - You should define a static final string for each property you wish to define. These strings will serve as keys into a hash table maintained by AbstractConfigElement. For example: 
     public static final HOST_NAME = "hostname";
    would define a property in the hash table for storing a host name.

  3. Getters/Setters - For each property name you define in the previous step, define the appropriate accessor methods. The implementation of these accessors should usually delegate to AbstractConfigElement. For example: 
       public void setHostname(String hostname)
   { putProperty(HOST_NAME, hostname); }

   public String getHostname()
   { return (String)getProperty(HOST_NAME); }
    Some accessor implementations may be more complex. See the UrlConfig object for a more involved example.

  4. String getClassLabel() - This is the label that will display in the drop-down menu for adding your configuration element.

  5. clone() - Your configuration element is expected to be cloneable. A basic implementation of this method would be 
       public Object clone() {
      MyConfig copy = new MyConfig();
      configureClone(copy);
      return copy;
   }
    It's important to call AbstractConfigElement.configureClone to properly clone the base class (which should be managing the state of your config element!).

  6. addConfigElement(ConfigElement) - A typical implementation of this method looks like 
       public void addConfigElement(ConfigElement config) {
      if (config instanceof MyConfig)
         updatePropertyIfAbsent((MyConfig)config);
   }
    where updatePropertyIfAbsent is handled by the super class.

  7. getGuiClass - return the name of the this class's corresponding GUI class.

Configuration GUI

Each configuration element you define can have a companion GUI class. It helps to have a little knowledge of Swing for this. Extend Swing's JPanel class and implement JMeter's org.apache.jmeter.gui.ModelSupported interface. Remember that you can review the UrlConfigGui example for hints if you get stuck.

  1. Data Members - You should possess at least two data members: a reference to your partner configuration element and a reference to a org.apache.jmeter.gui.NamePanel. You will likely have several others depending on how sophisticated your GUI is.

  2. Add Panels - The layout manager used for many of the panels used in JMeter is org.apache.jmeter.gui.VerticalLayout. As the name implies, it supports arranging other panels in a vertical fashion. You can define each of your panels in a get method and add them to the configuration GUI in a method called init. Once again, refer to UrlConfigGui for an example.

  3. Implement Listeners - Implement listeners for your GUI components. The UrlConfigGui serves as a satisfactory example.

  4. setModel - Use this method to have the model data member set on your GUI instance. Run init from inside this method also.

  5. updateGui - Use this method to set the GUI fields from the model.

Generative Controller

A generative controller is a controller that generates an Entry object for use by a Sampler. It is often convenient to extend org.apache.jmeter.control.AbstractGenerativeController. Be sure to implement org.apache.jmeter.gui.JMeterComponentModel and java.io.serializable.

  1. createEntry - This method is the raison d'etre of the org.apache.jmeter.control.SamplerController interface. The general idea is to construct an Entry object and populate it with config objects.

  2. clone - After you perform you cloning duties, be sure to pass the cloned instance to the standardCloneProc method so that base class cloning activities can complete.

  3. getClassLabel - This is the label displayed by the drop-down menu for the controller.

  4. getGuiClass - This should return a Class object for the associated GUI class.

Generative Controller GUI

A generative controller GUI class should extend JPanel and implement ModelSupported. If your controller GUI doesn't involve anything beyond the configuration GUI, you might be able to get away with inheriting from the configuration gui class you created a couple steps ago. If you do this, you need to at least override the setModel method to make sure that the correct model is set on the class. You'll be passed a controller object but you'll want to extract the config element from the controller to be used as the model for your base class (the config gui).

Sampler

Your Sampler subclass is responsible for actually performing the work using the information provided in the configuration element. The method of importance is 
public SampleResult sample(Entry e)
It is here that you extract configuration elements from the entry object you are passed. Then use these configuration elements to perform the task you extension is suppose to do.

Installation

Follow these steps to install your extension.

  1. Package the class files into a JAR file.
  2. Place the JAR file into the ext subdirectory of the JMeter root install directroy.
  3. Edit the bin/jmeter.properties file of the JMeter installation. Find the search_paths entry and add your JAR to the list. It should look like 
    search_paths=ApacheJMeter.jar;classes;../ext/YourJar.jar
  4. Run JMeter and watch the magic.

Tips

  1. You might consider using log4j as your logging utility since that's what JMeter uses. It's helpful for figuring out what's going on. Not all JMeter classes have been fully outfitted with logging statements. If things get nasty, you might have to add your own to JMeter and recompile it to see what is happening.

    If you do decide to use log4j and you set the priority (or level, as it will soon be called) to debug, you will probably see way more than you need to know. You can filter the JMeter stuff by making the following modifications to log4j.conf in the JMeter's bin directory. The bold text is added/modified 

    	# Set the appenders for the categories
	log4j.rootCategory=info,Root_Appender
	log4j.category.com.myfirm.jmeter=debug,
	log4j.category.org.apache.jmeter.control=debug
	log4j.category.org.apache.jmeter.gui.tree.NonGuiTree=INFO,File_Appender
    Note that the root (default) debugging has been set to info. This eliminates most log4j output from JMeter. The new line specifies the name of the package containing JMeter extensions. (com.yourfirm.jmeter) in this example. Note that it is not necessary to specify a particular class name. Also, note that no appenders are specified - just the trailing comma. If you specify Root_Appender here you'll see your message appear twice (because you specified the same appender twice). All you really want to do is override the priority.

  2. Implement clone carefully. This is an often overlooked method for a lot of folks. JMeter makes heavy use of cloning. Check out some of the JMeter coniguration elements and controllers to see how they do it. Notice that in most cases, a special method is usually invoked to perform base class cloning activities. For configuration elements, this is configureClone. For controllers, it is standardCloneProc.
Version:$Revision: 1.1 $