jmeterguicomponent.java

测试工具

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * 
 */

package org.apache.jmeter.gui;

import java.util.Collection;

import javax.swing.JPopupMenu;

import javax.swing.tree.TreeNode;
import org.apache.jmeter.testelement.TestElement;

/**
 * Implementing this interface indicates that the class is a JMeter GUI
 * Component. A JMeter GUI Component is essentially the GUI display code
 * associated with a JMeter Test Element. The writer of the component must take
 * care to make the component be consistent with the rest of JMeter's GUI look
 * and feel and behavior. Use of the provided abstract classes is highly
 * recommended to make this task easier.
 * 
 * @see AbstractJMeterGuiComponent
 * @see org.apache.jmeter.config.gui.AbstractConfigGui
 * @see org.apache.jmeter.assertions.gui.AbstractAssertionGui
 * @see org.apache.jmeter.control.gui.AbstractControllerGui
 * @see org.apache.jmeter.timers.gui.AbstractTimerGui
 * @see org.apache.jmeter.visualizers.gui.AbstractVisualizer
 * @see org.apache.jmeter.samplers.gui.AbstractSamplerGui
 * 
 */

public interface JMeterGUIComponent {

	/**
	 * Sets the name of the JMeter GUI Component. The name of the component is
	 * used in the Test Tree as the name of the tree node.
	 * 
	 * @param name
	 *            the name of the component
	 */
	void setName(String name);

	/**
	 * Gets the name of the JMeter GUI component. The name of the component is
	 * used in the Test Tree as the name of the tree node.
	 * 
	 * @return the name of the component
	 */
	String getName();

	/**
	 * Get the component's label. This label is used in drop down lists that
	 * give the user the option of choosing one type of component in a list of
	 * many. It should therefore be a descriptive name for the end user to see.
	 * It must be unique to the class.
	 * 
	 * It is also used by Help to find the appropriate location in the
	 * documentation.
	 * 
	 * Normally getLabelResource() should be overridden instead of
	 * this method; the definition of this method in AbstractJMeterGuiComponent
	 * is intended for general use.
	 * 
	 * @see #getLabelResource()
	 * @return GUI label for the component.
	 */
	String getStaticLabel();

	/**
	 * Get the component's resource name, which getStaticLabel uses to derive
	 * the component's label in the local language. The resource name is fixed,
	 * and does not vary with the selected language.
	 * 
	 * Normally this method should be overriden in preference to overriding
	 * getStaticLabel(). However where the resource name is not available or required,
	 * getStaticLabel() may be overridden instead.
	 * 
	 * @return the resource name
	 */
	String getLabelResource();

	/**
	 * Get the component's document anchor name. Used by Help to find the
	 * appropriate location in the documentation
	 * 
	 * @return Document anchor (#ref) for the component.
	 */
	String getDocAnchor();

	/**
	 * JMeter test components are separated into a model and a GUI
	 * representation. The model holds the data and the GUI displays it. The GUI
	 * class is responsible for knowing how to create and initialize with data
	 * the model class that it knows how to display, and this method is called
	 * when new test elements are created.
	 * 
	 * @return the Test Element object that the GUI component represents.
	 */
	TestElement createTestElement();

	/**
	 * GUI components are responsible for populating TestElements they create
	 * with the data currently held in the GUI components. This method should
	 * overwrite whatever data is currently in the TestElement as it is called
	 * after a user has filled out the form elements in the gui with new
	 * information.
	 * 
	 * @param element
	 *            the TestElement to modify
	 */
	void modifyTestElement(TestElement element);

	/**
	 * Test GUI elements can be disabled, in which case they do not become part
	 * of the test when run.
	 * 
	 * @return true if the element should be part of the test run, false
	 *         otherwise
	 */
	boolean isEnabled();

	/**
	 * Set whether this component is enabled.
	 * 
	 * @param enabled
	 *            true for enabled, false for disabled.
	 */
	void setEnabled(boolean enabled);

	/**
	 * When a user right-clicks on the component in the test tree, or selects
	 * the edit menu when the component is selected, the component will be asked
	 * to return a JPopupMenu that provides all the options available to the
	 * user from this component.
	 * 
	 * @return a JPopupMenu appropriate for the component.
	 */
	JPopupMenu createPopupMenu();

	/**
	 * The GUI must be able to extract the data from the TestElement and update
	 * all GUI fields to represent those data. This method is called to allow
	 * JMeter to show the user the GUI that represents the test element's data.
	 * 
	 * @param element
	 *            the TestElement to configure
	 */
	void configure(TestElement element);

	/**
	 * This is the list of add menu categories this gui component will be
	 * available under. For instance, if this represents a Controller, then the
	 * MenuFactory.CONTROLLERS category should be in the returned collection.
	 * When a user right-clicks on a tree element and looks through the "add"
	 * menu, which category your GUI component shows up in is determined by
	 * which categories are returned by this method. Most GUI's belong to only
	 * one category, but it is possible for a component to exist in multiple
	 * categories.
	 * 
	 * @return a Collection of Strings, where each element is one of the
	 *         constants defined in MenuFactory
	 * 
	 * @see org.apache.jmeter.gui.util.MenuFactory
	 */
	Collection getMenuCategories();

	/**
	 * Sets the tree node which this component is associated with.
	 * 
	 * @param node
	 *            the tree node corresponding to this component
	 */
	void setNode(TreeNode node);
    
	/**
	 * Clear the gui and return it to initial default values. This is necessary
	 * because most gui classes are instantiated just once and re-used for
	 * multiple test element objects and thus they need to be cleared between
	 * use.
	 */
	public void clearGui();
	// N.B. originally called clear()
	// @see also Clearable
}