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.gui;
020:
021: import java.util.Collection;
022:
023: import javax.swing.JPopupMenu;
024:
025: import javax.swing.tree.TreeNode;
026: import org.apache.jmeter.testelement.TestElement;
027:
028: /**
029: * Implementing this interface indicates that the class is a JMeter GUI
030: * Component. A JMeter GUI Component is essentially the GUI display code
031: * associated with a JMeter Test Element. The writer of the component must take
032: * care to make the component be consistent with the rest of JMeter's GUI look
033: * and feel and behavior. Use of the provided abstract classes is highly
034: * recommended to make this task easier.
035: *
036: * @see AbstractJMeterGuiComponent
037: * @see org.apache.jmeter.config.gui.AbstractConfigGui
038: * @see org.apache.jmeter.assertions.gui.AbstractAssertionGui
039: * @see org.apache.jmeter.control.gui.AbstractControllerGui
040: * @see org.apache.jmeter.timers.gui.AbstractTimerGui
041: * @see org.apache.jmeter.visualizers.gui.AbstractVisualizer
042: * @see org.apache.jmeter.samplers.gui.AbstractSamplerGui
043: *
044: */
045:
046: public interface JMeterGUIComponent {
047:
048: /**
049: * Sets the name of the JMeter GUI Component. The name of the component is
050: * used in the Test Tree as the name of the tree node.
051: *
052: * @param name
053: * the name of the component
054: */
055: void setName(String name);
056:
057: /**
058: * Gets the name of the JMeter GUI component. The name of the component is
059: * used in the Test Tree as the name of the tree node.
060: *
061: * @return the name of the component
062: */
063: String getName();
064:
065: /**
066: * Get the component's label. This label is used in drop down lists that
067: * give the user the option of choosing one type of component in a list of
068: * many. It should therefore be a descriptive name for the end user to see.
069: * It must be unique to the class.
070: *
071: * It is also used by Help to find the appropriate location in the
072: * documentation.
073: *
074: * Normally getLabelResource() should be overridden instead of
075: * this method; the definition of this method in AbstractJMeterGuiComponent
076: * is intended for general use.
077: *
078: * @see #getLabelResource()
079: * @return GUI label for the component.
080: */
081: String getStaticLabel();
082:
083: /**
084: * Get the component's resource name, which getStaticLabel uses to derive
085: * the component's label in the local language. The resource name is fixed,
086: * and does not vary with the selected language.
087: *
088: * Normally this method should be overriden in preference to overriding
089: * getStaticLabel(). However where the resource name is not available or required,
090: * getStaticLabel() may be overridden instead.
091: *
092: * @return the resource name
093: */
094: String getLabelResource();
095:
096: /**
097: * Get the component's document anchor name. Used by Help to find the
098: * appropriate location in the documentation
099: *
100: * @return Document anchor (#ref) for the component.
101: */
102: String getDocAnchor();
103:
104: /**
105: * JMeter test components are separated into a model and a GUI
106: * representation. The model holds the data and the GUI displays it. The GUI
107: * class is responsible for knowing how to create and initialize with data
108: * the model class that it knows how to display, and this method is called
109: * when new test elements are created.
110: *
111: * @return the Test Element object that the GUI component represents.
112: */
113: TestElement createTestElement();
114:
115: /**
116: * GUI components are responsible for populating TestElements they create
117: * with the data currently held in the GUI components. This method should
118: * overwrite whatever data is currently in the TestElement as it is called
119: * after a user has filled out the form elements in the gui with new
120: * information.
121: *
122: * @param element
123: * the TestElement to modify
124: */
125: void modifyTestElement(TestElement element);
126:
127: /**
128: * Test GUI elements can be disabled, in which case they do not become part
129: * of the test when run.
130: *
131: * @return true if the element should be part of the test run, false
132: * otherwise
133: */
134: boolean isEnabled();
135:
136: /**
137: * Set whether this component is enabled.
138: *
139: * @param enabled
140: * true for enabled, false for disabled.
141: */
142: void setEnabled(boolean enabled);
143:
144: /**
145: * When a user right-clicks on the component in the test tree, or selects
146: * the edit menu when the component is selected, the component will be asked
147: * to return a JPopupMenu that provides all the options available to the
148: * user from this component.
149: *
150: * @return a JPopupMenu appropriate for the component.
151: */
152: JPopupMenu createPopupMenu();
153:
154: /**
155: * The GUI must be able to extract the data from the TestElement and update
156: * all GUI fields to represent those data. This method is called to allow
157: * JMeter to show the user the GUI that represents the test element's data.
158: *
159: * @param element
160: * the TestElement to configure
161: */
162: void configure(TestElement element);
163:
164: /**
165: * This is the list of add menu categories this gui component will be
166: * available under. For instance, if this represents a Controller, then the
167: * MenuFactory.CONTROLLERS category should be in the returned collection.
168: * When a user right-clicks on a tree element and looks through the "add"
169: * menu, which category your GUI component shows up in is determined by
170: * which categories are returned by this method. Most GUI's belong to only
171: * one category, but it is possible for a component to exist in multiple
172: * categories.
173: *
174: * @return a Collection of Strings, where each element is one of the
175: * constants defined in MenuFactory
176: *
177: * @see org.apache.jmeter.gui.util.MenuFactory
178: */
179: Collection getMenuCategories();
180:
181: /**
182: * Sets the tree node which this component is associated with.
183: *
184: * @param node
185: * the tree node corresponding to this component
186: */
187: void setNode(TreeNode node);
188:
189: /**
190: * Clear the gui and return it to initial default values. This is necessary
191: * because most gui classes are instantiated just once and re-used for
192: * multiple test element objects and thus they need to be cleared between
193: * use.
194: */
195: public void clearGui();
196: // N.B. originally called clear()
197: // @see also Clearable
198: }
|