mstover1 2003/06/23 09:35:13
Modified: src/core/org/apache/jmeter/gui
AbstractJMeterGuiComponent.java
JMeterGUIComponent.java
src/core/org/apache/jmeter/visualizers Visualizer.java
package.html
src/core/org/apache/jmeter/visualizers/gui
AbstractVisualizer.java
Log:
Starting the long road of javadoc updates
Revision Changes Path
1.23 +33 -21
jakarta-jmeter/src/core/org/apache/jmeter/gui/AbstractJMeterGuiComponent.java
Index: AbstractJMeterGuiComponent.java
===================================================================
RCS file:
/home/cvs/jakarta-jmeter/src/core/org/apache/jmeter/gui/AbstractJMeterGuiComponent.java,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -r1.22 -r1.23
--- AbstractJMeterGuiComponent.java 6 Jun 2003 14:02:08 -0000 1.22
+++ AbstractJMeterGuiComponent.java 23 Jun 2003 16:35:12 -0000 1.23
@@ -118,29 +118,34 @@
setName(getStaticLabel());
}
- /* Implements JMeterGUIComponent.setName(String) */
+ /**
+ * Provides a default implementation for the name property. It's unlikely
developers will need to override.
+ */
public void setName(String name)
{
namePanel.setName(name);
}
- /* (non-JavaDoc)
- * Implements JMeterGUIComponent.isEnabled()
- * Overrides Component.isEnabled()
+ /**
+ * Provides a default implementation for the enabled property. It's unlikely
developers will need to override.
*/
public boolean isEnabled()
{
return enabled;
}
- /* Implements JMeterGUIComponent.setEnabled(boolean) */
+ /**
+ * Provides a default implementation for the enabled property. It's unlikely
developers will need to override.
+ */
public void setEnabled(boolean e)
{
log.debug("Setting enabled: " + e);
enabled = e;
}
- /* Implements JMeterGUIComponent.getName() */
+ /**
+ * Provides a default implementation for the name property. It's unlikely
developers will need to override.
+ */
public String getName()
{
return getNamePanel().getName();
@@ -149,8 +154,8 @@
/**
* Provides the Name Panel for extending classes. Extending classes are
* free to place it as desired within the component, or not at all. Most
- * components place the NamePanel automatically when calling
- * [EMAIL PROTECTED] #makeTitlePanel()}.
+ * components place the NamePanel automatically by calling
+ * [EMAIL PROTECTED] #makeTitlePanel()} instead of directly calling this method.
*
* @return a NamePanel containing the name of this component
*/
@@ -165,7 +170,7 @@
* to the name returned from the component's
* [EMAIL PROTECTED] JMeterGUIComponent#getStaticLabel() getStaticLabel()}
method.
* Most components place this label automatically by calling
- * [EMAIL PROTECTED] #makeTitlePanel()}.
+ * [EMAIL PROTECTED] #makeTitlePanel()} instead of directly calling this method.
*
* @return a JLabel which subclasses can add to their GUI
*/
@@ -178,7 +183,7 @@
}
/**
- * A newly created component can be initialized with the contents of
+ * A newly created gui component can be initialized with the contents of
* a Test Element object by calling this method. The component is
* responsible for querying the Test Element object for the
* relevant information to display in its GUI.
@@ -203,6 +208,10 @@
}
}
+ /**
+ * Provides a default implementat that resets the name field to the value of
getStaticLabel(), and sets enabled to true. Your GUI may need more things
+ * cleared, in which case you should override, clear the extra fields, and
still call super.clear().
+ */
public void clear()
{
setName(getStaticLabel());
@@ -211,9 +220,9 @@
/**
* This provides a convenience for extenders when they implement the
- * [EMAIL PROTECTED] JMeterGUIComponent#createTestElement()} method. This
method
+ * [EMAIL PROTECTED] JMeterGUIComponent#modifyTestElement(TestElement)} method.
This method
* will set the name, gui class, and test class for the created Test
- * Element. It should be called by every extending class when creating
+ * Element. It should be called by every extending class when
creating/modifying
* Test Elements, as that will best assure consistent behavior.
*
* @param mc the TestElement being created.
@@ -237,7 +246,9 @@
mc.setProperty(new BooleanProperty(TestElement.ENABLED, enabled));
}
- /* Implements JMeterGUIComponent.setNode(JMeterTreeNode) */
+ /**
+ * Provides a default implementation for the node property. It is unlikely
developers would need to override this method.
+ */
public void setNode(JMeterTreeNode node)
{
this.node = node;
@@ -245,9 +256,7 @@
}
/**
- * Get the tree node associated with this component.
- *
- * @return JMeterTreeNode the tree node associated with this component
+ * Provides a default implementation for the node property. It is unlikely
developers would need to override this method.
*/
protected JMeterTreeNode getNode()
{
@@ -271,8 +280,9 @@
}
/**
- * Create a Border which can be added to JMeter components. Components
- * typically set this as their border in their init method.
+ * Create a top-level Border which can be added to JMeter components.
Components
+ * typically set this as their border in their init method. It simply provides
a nice spacing between the GUI components used and the edges of the
+ * window in which they appear.
*
* @return a Border for JMeter components
*/
@@ -285,7 +295,8 @@
* Create a scroll panel that sets it's preferred size to it's minimum
* size. Explicitly for scroll panes that live inside other scroll panes,
* or within containers that stretch components to fill the area they exist
- * in.
+ * in. Use this for any component you would put in a scroll pane (such as
TextAreas, tables, JLists, etc). It is here for convenience and to avoid
+ * duplicate code. JMeter displays best if you follow this custom.
*
* @param comp the component which should be placed inside the scroll pane
* @return a JScrollPane containing the specified component
@@ -301,7 +312,8 @@
* Create a scroll panel that sets it's preferred size to it's minimum
* size. Explicitly for scroll panes that live inside other scroll panes,
* or within containers that stretch components to fill the area they exist
- * in.
+ * in. Use this for any component you would put in a scroll pane (such as
TextAreas, tables, JLists, etc). It is here for convenience and to avoid
+ * duplicate code. JMeter displays best if you follow this custom.
*
* @see javax.swing.ScrollPaneConstants
*
1.10 +15 -14
jakarta-jmeter/src/core/org/apache/jmeter/gui/JMeterGUIComponent.java
Index: JMeterGUIComponent.java
===================================================================
RCS file:
/home/cvs/jakarta-jmeter/src/core/org/apache/jmeter/gui/JMeterGUIComponent.java,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- JMeterGUIComponent.java 29 May 2003 13:33:56 -0000 1.9
+++ JMeterGUIComponent.java 23 Jun 2003 16:35:12 -0000 1.10
@@ -105,24 +105,24 @@
* 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.
+ * name for the end user to see. It must be unique to the class.
*
* @return GUI label for the component.
*/
String getStaticLabel();
/**
- * When a test is started, GUI components are converted into
- * test elements. This is the method called on each component
- * to get the test element equivalent.
+ * 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 should be able to set a given TestElement's data to
- * what is represented by the GUI.
+ * 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
*/
@@ -153,19 +153,19 @@
JPopupMenu createPopupMenu();
/**
- * A newly created component can be initialized with the contents of
- * a Test Element object by calling this method. The component is
- * responsible for querying the Test Element object for the
- * relevant information to display in its GUI.
+ * 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 menu categories this gui component will be available
+ * 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.
+ * 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
@@ -180,7 +180,8 @@
void setNode(JMeterTreeNode node);
/**
- * Clear the gui and return it to initial default values.
+ * 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.
* TODO: implement this in all gui classes.
*/
public void clear();
1.3 +5 -7
jakarta-jmeter/src/core/org/apache/jmeter/visualizers/Visualizer.java
Index: Visualizer.java
===================================================================
RCS file:
/home/cvs/jakarta-jmeter/src/core/org/apache/jmeter/visualizers/Visualizer.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- Visualizer.java 5 Feb 2003 05:12:10 -0000 1.2
+++ Visualizer.java 23 Jun 2003 16:35:12 -0000 1.3
@@ -57,13 +57,11 @@
import org.apache.jmeter.samplers.SampleResult;
/**
- * This interface defines those methods needed by a visualizer
- * to be run and accessed.
+ * Implement this method to be a Visualizer for JMeter. This interface defines a
single method, "add()", that provides the means by which
+ * [EMAIL PROTECTED] org.apache.jmeter.samplers.SampleResult SampleResults} are
passed to the implementing visualizer for display/logging.
+ * The easiest way to create the visualizer is to extend the [EMAIL PROTECTED]
org.apache.jmeter.visualizers.gui.AbstractVisualizer AbstractVisualizer} class.
*
- * All visualizer pluging must implement this inteface in order
- * to be plugged into JMeter.
- *
- * @author <a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>
+ * @author <a href="mailto:[EMAIL PROTECTED]">Michael Stover</a>
* @version $Revision$ $Date$
*/
public interface Visualizer {
1.2 +2 -0
jakarta-jmeter/src/core/org/apache/jmeter/visualizers/package.html
Index: package.html
===================================================================
RCS file:
/home/cvs/jakarta-jmeter/src/core/org/apache/jmeter/visualizers/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 23 Apr 2003 14:27:23 -0000 1.1
+++ package.html 23 Jun 2003 16:35:12 -0000 1.2
@@ -7,6 +7,8 @@
This package contains the interfaces that have to be implemented by
any class wishing to display or present data collected in SampleResults.
+<p>
+The primary classes/interfaces to be concerned with for implementers is the [EMAIL
PROTECTED] org.apache.jmeter.visualizers.Visualizer Visualizer} interface, and the
[EMAIL PROTECTED] org.apache.jmeter.visualizers.gui.AbstractVisualizer
AbstractVisualizer} abstract class.
</body>
</html>
1.18 +40 -2
jakarta-jmeter/src/core/org/apache/jmeter/visualizers/gui/AbstractVisualizer.java
Index: AbstractVisualizer.java
===================================================================
RCS file:
/home/cvs/jakarta-jmeter/src/core/org/apache/jmeter/visualizers/gui/AbstractVisualizer.java,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- AbstractVisualizer.java 13 Jun 2003 14:51:51 -0000 1.17
+++ AbstractVisualizer.java 23 Jun 2003 16:35:12 -0000 1.18
@@ -24,7 +24,37 @@
/**
* This is the base class for JMeter GUI components which can display test
- * results in some way.
+ * results in some way. It provides the following conveniences to developers:
+ * <ul>
+ * <li>Implements the [EMAIL PROTECTED] org.apache.jmeter.gui.JMeterGUIComponent
JMeterGUIComponent} interface that allows your Gui visualizer to
+ * "plug-in" to the JMeter GUI environment. Provides implementations for the
following methods:
+ * <ul><li>[EMAIL PROTECTED]
org.apache.jmeter.gui.JMeterGUIComponent#configure(TestElement)
configure(TestElement)}. Any additional parameters of your Visualizer
+ * need to be handled by you.</li>
+ * <li>[EMAIL PROTECTED]
org.apache.jmeter.gui.JMeterGUIComponent#createTestElement() createTestElement()}.
For most purposes, the default
+ * [EMAIL PROTECTED] org.apache.jmeter.reporters.ResultCollector ResultCollector}
created by this method is sufficient.</li>
+ * <li>[EMAIL PROTECTED] org.apache.jmeter.gui.JMeterGUIComponent#getMenuCategories
getMenuCategories()}. To control where in the GUI your visualizer
+ * can be added.</li>
+ * <li>[EMAIL PROTECTED]
org.apache.jmeter.gui.JMeterGUIComponent#modifyTestElement(TestElement)
modifyTestElement(TestElement)}. Again, additional
+ * parameters you require have to be handled by you.</li>
+ * <li>[EMAIL PROTECTED] org.apache.jmeter.gui.JMeterGUIComponent#createPopupMenu()
createPopupMenu()}. </li>
+ * </ul>
+ * <li>Provides convenience methods to help you make a JMeter-compatible GUI:
+ * <ul><li>[EMAIL PROTECTED] makeTitlePanel() makeTitlePanel()}. Returns a panel
that includes the name of the component, and a FilePanel that allows users
+ * to control what file samples are logged to.</li>
+ * <li>[EMAIL PROTECTED] getModel() getModel()} and [EMAIL PROTECTED]
setModel(ResultCollector) setModel(ResultCollector)} methods for setting and getting
the model class that handles the receiving
+ * and logging of sample results.</li>
+ * </ul></ul>
+ * For most developers, making a new visualizer is primarly for the purpose of
either calculating new statistics on the sample results that other
+ * visualizers don't calculate, or displaying the results visually in a new and
interesting way. Making a new visualizer for either of these
+ * purposes is easy - just extend this class and implement the [EMAIL PROTECTED]
org.apache.jmeter.visualizers.Visualizer#add(SampleResult) add(SampleResult)} method
+ * and display the results as you see fit. This AbstractVisualizer and the default
[EMAIL PROTECTED] org.apache.jmeter.reporters.ResultCollector ResultCollector} handle
+ * logging and registering to receive SampleEvents for you - all you need to do is
include the JPanel created by makeTitlePanel somewhere in
+ * your gui to allow users set the log file.
+ * <p>
+ * If you are doing more than that, you may need to extend [EMAIL PROTECTED]
org.apache.jmeter.reporters.ResultCollector ResultCollector} as well and modify the
+ * [EMAIL PROTECTED] configure(TestElement) configure(TestElement)}, [EMAIL
PROTECTED] modifyTestElement(TestElement) modifyTestElement(TestElement)}, and
+ * [EMAIL PROTECTED] createTestElement() createTestElement()} methods to create and
modify your alternate ResultCollector. For an example of this, see the
+ * [EMAIL PROTECTED] org.apache.jmeter.visualizers.MailerVisualizer
MailerVisualizer}.
* Copyright: 2000,2003
*
* @author Michael Stover
@@ -76,6 +106,12 @@
return errorLogging;
}
+ /**
+ * Provides access to the ResultCollector model class for extending
implementations. Using this method and setModel(ResultCollector) is only necessary
+ * if your visualizer requires a differently behaving ResultCollector. Using
these methods will allow maximum reuse of the methods provided
+ * by AbstractVisualizer in this event.
+ * @return
+ */
protected ResultCollector getModel()
{
return collector;
@@ -260,6 +296,8 @@
}
/**
+ * Provides extending classes the opportunity to set the ResultCollector model
for the Visualizer. This is useful to allow maximum reuse of the
+ * methods from AbstractVisualizer.
* @param collector
*/
protected void setModel(ResultCollector collector)
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
